[README-FIRST]: Project Backlog & Issue Guide

# [README-FIRST]: Project Backlog & Issue Guide

Welcome to **MCP Context Forge**! This pinned issue explains how our backlog is organized, how we prioritize work, and how you can contribute effectively.

---

## 📋 Quick Links

| Action | Link |
|--------|------|
| 🐛 Report a Bug | [Bug Report Template](https://github.com/IBM/mcp-context-forge/issues/new?template=bug-report-code.md) |
| ✨ Request a Feature | [Feature Request Template](https://github.com/IBM/mcp-context-forge/issues/new?template=feature-request.md) |
| 📝 Documentation Issue | [Docs Template](https://github.com/IBM/mcp-context-forge/issues/new?template=docs-issue.md) |
| 🧹 Chore/Maintenance | [Chore Template](https://github.com/IBM/mcp-context-forge/issues/new?template=chore-task--devops--linting--maintenance-.md) |
| 🧪 Testing Issue | [Testing Template](https://github.com/IBM/mcp-context-forge/issues/new?template=testing--bug--unit--manual--or-new-test-.md) |
| 🔒 Security Issue | [Report a Vulnerability](https://github.com/IBM/mcp-context-forge/security/advisories/new) |
| 📖 Contributing Guide | [CONTRIBUTING.md](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md) |
| 📚 Documentation | [ibm.github.io/mcp-context-forge](https://ibm.github.io/mcp-context-forge/) |

---

## 🔒 Security Reporting

> **⚠️ Do NOT file security vulnerabilities as public issues.**

If you discover a security vulnerability, please report it privately:

1. **Use GitHub's Security Advisory** — [Report a vulnerability](https://github.com/IBM/mcp-context-forge/security/advisories/new)
2. **Or email** — Follow instructions in [SECURITY.md](https://github.com/IBM/mcp-context-forge/blob/main/SECURITY.md)

**What happens next:**
- We will acknowledge your report within 48 hours
- We will work with you to understand and validate the issue
- We will develop and test a fix
- We will coordinate disclosure timing with you

**CVE Tracking:** Formal CVE identifiers will be assigned starting with **Release 1.0.0-GA** (Feb 24, 2026). Until then, security fixes are tracked internally and noted in release notes.

For complete security policies, hardening guides, and our security posture, see **[SECURITY.md](https://github.com/IBM/mcp-context-forge/blob/main/SECURITY.md)**.

---

## 🚦 Project Status

| Attribute | Value |
|-----------|-------|
| **Current Version** | 1.0.0-BETA-2 |
| **Status** | Beta — Production use at your own risk |
| **Next Milestone** | [1.0.0-RC1](https://github.com/IBM/mcp-context-forge/milestone/10) (Feb 3, 2026) |
| **GA Target** | Feb 24, 2026 |
| **License** | Apache 2.0 |

**Beta Software Notice:** MCP Context Forge is under active development. APIs may change between releases. We recommend pinning to specific versions in production and testing upgrades in staging environments first.

---

## 🏷️ Issue Types: Feature vs Task vs Bug

Every issue should be categorized as one of these three types:

### ✨ Feature (`enhancement`)
A **Feature** adds new functionality or significantly enhances existing capabilities. Features require design consideration and often span multiple files or components.

**Examples:**
| Issue | Why it's a Feature |
|-------|-------------------|
| `[EPIC][SDK]: TypeScript SDK auto-generation` | Adds entirely new capability |
| `[FEATURE]: Add LangChain-based MCP Agent` | New integration component |
| `[EPIC][TESTING]: Automated MCP server compatibility regression suite` | Major new test automation infrastructure |
| `[FEATURE]: Export MCP session pool metrics to Prometheus` | New observability capability |
| `[EPIC][UI]: Notification center and alert management` | Significant new UI functionality |
| `[CHORE]: Implement GitHub Actions matrix for multi-Python testing` | Major automation feature (not just maintenance) |

### 📋 Task (`chore`, `testing`, `documentation`)
A **Task** is work that needs to be done but doesn't add new product functionality. Tasks maintain, test, document, or clean up existing code.

**Examples:**
| Issue | Why it's a Task |
|-------|-----------------|
| `[TESTING][SECURITY]: RBAC manual test plan` | Manual testing work (executing test plans) |
| `[TESTING][SECURITY]: Session management manual test plan` | Following documented test procedures |
| `[CHORE]: Remove unused PromptNotFoundError import` | Code cleanup |
| `[CLEANUP][SONAR]: Dead code - unused function in router` | Technical debt cleanup |
| `[CHORE]: Update Python dependencies` | Routine maintenance |
| `[DOCS]: Update API reference for new endpoints` | Documentation updates |

### 🐛 Bug (`bug`)
A **Bug** is something that's broken, behaving unexpectedly, or not working as documented.

**Examples:**
| Issue | Why it's a Bug |
|-------|---------------|
| `[BUG]: anyio cancel scope spin loop causes 100% CPU` | Unexpected behavior causing system issues |
| `[BUG]: SSO admin tokens include teams key, preventing bypass` | Authentication not working correctly |
| `[BUG]: UI Export Config button missing after pagination` | UI element disappeared unexpectedly |
| `[BUG]: Multiple gateway import failing with unique constraint` | Feature not working as intended |
| `[SECURITY][SONAR]: ReDoS vulnerability in validation patterns` | Security defect |

### Quick Decision Guide

```
Is something broken or not working as expected?
  → 🐛 Bug

Does it add NEW functionality or significantly enhance existing?
  → ✨ Feature

Is it maintenance, cleanup, testing execution, or documentation?
  → 📋 Task
```

**Special cases:**
- **Manual test plans** = Task (executing existing test procedures)
- **Test automation infrastructure** = Feature (building new capability)
- **Chores that implement major automation** = Feature
- **Security vulnerabilities** = Bug (with `security` label)

---

## 🎯 MoSCoW Prioritization

We use **MoSCoW** to prioritize issues. Look for these labels:

| Label | Priority | Meaning | Examples |
|-------|----------|---------|----------|
| `MUST` | P1 🔴 | **Critical** — Release blockers. Non-negotiable. | Security fixes, core functionality broken, blocking bugs |
| `SHOULD` | P2 🟠 | **Important** — High value, include if possible. | Performance improvements, important features, UX fixes |
| `COULD` | P3 🟡 | **Nice-to-have** — Minimal impact if deferred. | Minor enhancements, cleanup, nice-to-have features |
| `WOULD` | P4 🟢 | **Future** — Not this release, backlog items. | Future ideas, low-priority enhancements |

**No priority label?** The issue is in `triage` awaiting review.

---

## 📦 Release Roadmap

We follow a monthly release cadence with themed milestones:

| Milestone | Target Date | Theme | Status |
|-----------|-------------|-------|--------|
| **Release 1.0.0-RC1** | Feb 3, 2026 | Security, Linting, Catalog, UI Polish | 🔄 Active |
| **Release 1.0.0-GA** | Feb 24, 2026 | Technical Debt, A2A, MCP Standard Sync | 📋 Planned |
| **Release 1.1.0** | Mar 31, 2026 | Technical Debt and Quality | 📋 Planned |
| **Release 1.2.0** | Apr 28, 2026 | Documentation, Bugfixes | 📋 Planned |
| **Release 1.3.0** | May 26, 2026 | New MCP Servers and Agents | 📋 Planned |
| **Release 1.4.0** | Jun 22, 2026 | Enterprise Features, Federation, Performance | 📋 Planned |
| **Release 1.5.0** | Jul 20, 2026 | Ecosystem Integrations, Observability, Plugin Marketplace | 📋 Planned |
| **Release 1.6.0** | Aug 16, 2026 | Collaboration, Workflow, Security Posture | 📋 Planned |

**Key Milestones:**
- **1.0.0-GA** — First stable release, CVE tracking begins, semantic versioning enforced
- **1.2.0** — Documentation focus, improved onboarding
- **1.4.0** — Enterprise-ready features (federation, performance)

View live progress: [Milestones](https://github.com/IBM/mcp-context-forge/milestones) | [Full Roadmap](https://ibm.github.io/mcp-context-forge/architecture/roadmap/)

---

## 🏷️ Label Reference

### Issue Type
| Label | Description |
|-------|-------------|
| `bug` | Something isn't working |
| `enhancement` | New feature or improvement |
| `documentation` | Docs improvements |
| `testing` | Unit, E2E, manual, or automated testing |
| `manual-testing` | Manual test plans requiring human execution |
| `chore` | Maintenance, linting, dependency updates |
| `security` | Security improvements or fixes |
| `epic` | Large feature spanning multiple issues |

### Status
| Label | Description |
|-------|-------------|
| `triage` | Awaiting review and prioritization |
| `planned` | Scheduled for a future release |
| `blocked` | Waiting on another issue/PR |
| `awaiting-user` | Needs feedback from reporter |
| `fixed` | Issue resolved (pending close) |
| `wontfix` | Will not be addressed |
| `duplicate` | Already tracked elsewhere |

### Technology
| Label | Description |
|-------|-------------|
| `python` | Python / FastAPI backend |
| `go` | Go programming |
| `rust` | Rust programming |
| `javascript` / `typescript` | JS/TS code |
| `frontend` | HTML, CSS, JavaScript UI |
| `java` / `haskell` | Other languages |

### Component
| Label | Description |
|-------|-------------|
| `mcpgateway.translate` | stdio→HTTP translator |
| `mcpgateway.wrapper` | Gateway wrapper |
| `plugins` | Plugin framework |
| `ui` | Admin UI |
| `database` | Database layer |
| `helm` | Helm charts |
| `devops` | Containers, CI/CD, deployment |
| `cicd` | GitHub Actions |
| `rbac` | Role-based access control |
| `observability` | Logging, metrics, tracing |

### Protocol
| Label | Description |
|-------|-------------|
| `mcp-protocol` | MCP specification alignment |
| `mcp-2025-06-18` | MCP 2025-06-18 spec |
| `a2a` | Agent-to-Agent protocol |

### Special
| Label | Description |
|-------|-------------|
| `good first issue` | Great for newcomers! |
| `help wanted` | Extra attention needed |
| `priority` | High-priority queue |
| `sonar` | SonarQube findings |
| `experimental` | Experimental features |

---

## 🐛 How to File a Bug

1. **Search first** — Check [existing issues](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aissue)
2. **Use the template** — Click [Bug Report](https://github.com/IBM/mcp-context-forge/issues/new?template=bug-report-code.md)
3. **Provide details:**
   - Clear summary of the problem
   - Steps to reproduce (numbered list)
   - Expected vs actual behavior
   - Environment info (from `/version` endpoint)
   - Logs/error output (⚠️ **no secrets!**)
4. **Select affected component** (API, UI, wrapper, etc.)

**A great bug report includes:**
```markdown
### 🐞 Bug Summary
The gateway returns 500 error when registering a gateway with special characters in the name.

### 🔁 Steps to Reproduce
1. Start the gateway with `make dev`
2. POST to /gateways with name containing "&"
3. Observe 500 Internal Server Error

### 🤔 Expected Behavior
Should return 400 Bad Request with validation error message.

### 📓 Logs
ValidationError: name contains invalid characters

### 🧠 Environment
| Key | Value |
|-----|-------|
| Version | v0.9.5 |
| Python | 3.11.4 |
| OS | Ubuntu 22.04 |
```

---

## ✨ How to Request a Feature

1. **Use the template** — Click [Feature Request](https://github.com/IBM/mcp-context-forge/issues/new?template=feature-request.md)
2. **Describe the epic** — What's the big picture goal?
3. **Add user stories** — Who benefits and how?
4. **Include acceptance criteria** — Use Gherkin format:
   ```gherkin
   Scenario: User creates API token with custom expiry
     Given I am logged in as admin
     When I create a token with 30-day expiry
     Then the token should expire after 30 days
   ```
5. **Check MCP compliance** — Does it align with the [MCP specification](https://modelcontextprotocol.io)?

---

## 🤝 Contributing

We welcome contributions! Here's the flow:

1. **Find an issue** — Look for [`good first issue`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3A%22help+wanted%22)
2. **Comment** — Let us know you're working on it
3. **Fork & branch** — Create a feature branch
4. **Code** — Follow our [coding standards](https://github.com/IBM/mcp-context-forge/blob/main/CLAUDE.md)
5. **Test** — Run `make lint && make test && make coverage`
6. **PR** — Submit with signed commits (`git commit -s`)
7. **Review** — Address feedback, get 2 LGTMs

See [CONTRIBUTING.md](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md) for full details.

---

## 🔍 Finding Issues to Work On

| Looking for... | Filter |
|----------------|--------|
| Beginner-friendly | [`good first issue`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3A%22good+first+issue%22) |
| Needs help | [`help wanted`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3A%22help+wanted%22) |
| Bugs to fix | [`bug`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3Abug) |
| Documentation | [`documentation`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3Adocumentation) |
| Critical items | [`MUST`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3AMUST) |
| Quick wins | [`COULD` + `chore`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3ACOULD+label%3Achore) |
| Security items | [`security`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3Asecurity) |
| Needs triage | [`triage`](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aopen+label%3Atriage) |

---

## 📊 Backlog at a Glance

- **600+ open issues** across all milestones
- **8 planned releases** through August 2026
- **5 issue templates** for consistent filing
- **60+ labels** for precise categorization
- **MoSCoW prioritization** (MUST/SHOULD/COULD/WOULD)

---

## 📚 Documentation Structure

Our documentation lives in multiple places:

| Resource | What's There |
|----------|-------------|
| [README.md](https://github.com/IBM/mcp-context-forge/blob/main/README.md) | Quick start, installation, configuration |
| [Docs Site](https://ibm.github.io/mcp-context-forge/) | Full documentation, tutorials, API reference |
| [SECURITY.md](https://github.com/IBM/mcp-context-forge/blob/main/SECURITY.md) | Security policies, hardening, vulnerability reporting |
| [CONTRIBUTING.md](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md) | Contribution guidelines, code standards |
| [CLAUDE.md](https://github.com/IBM/mcp-context-forge/blob/main/CLAUDE.md) | AI coding assistant guidelines |
| [Architecture](https://ibm.github.io/mcp-context-forge/architecture/) | ADRs, design decisions, roadmap |
| [FAQ](https://ibm.github.io/mcp-context-forge/faq/) | Common questions answered |

---

## ❓ Questions?

- Open a [Question issue](https://github.com/IBM/mcp-context-forge/issues/new) with the `question` label
- Check the [FAQ](https://ibm.github.io/mcp-context-forge/faq/)
- Read the [Documentation](https://ibm.github.io/mcp-context-forge/)

---

*This issue is pinned for easy reference. Last updated: January 2025*

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[README-FIRST]: Project Backlog & Issue Guide #2502

[README-FIRST]: Project Backlog & Issue Guide

📋 Quick Links

🔒 Security Reporting

🚦 Project Status

🏷️ Issue Types: Feature vs Task vs Bug

✨ Feature (`enhancement`)

📋 Task (`chore`, `testing`, `documentation`)

🐛 Bug (`bug`)

Quick Decision Guide

🎯 MoSCoW Prioritization

📦 Release Roadmap

🏷️ Label Reference

Issue Type

Status

Technology

Component

Protocol

Special

🐛 How to File a Bug

✨ How to Request a Feature

🤝 Contributing

🔍 Finding Issues to Work On

📊 Backlog at a Glance

📚 Documentation Structure

❓ Questions?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Action	Link
🐛 Report a Bug	Bug Report Template
✨ Request a Feature	Feature Request Template
📝 Documentation Issue	Docs Template
🧹 Chore/Maintenance	Chore Template
🧪 Testing Issue	Testing Template
🔒 Security Issue	Report a Vulnerability
📖 Contributing Guide	CONTRIBUTING.md
📚 Documentation	ibm.github.io/mcp-context-forge

Attribute	Value
Current Version	1.0.0-BETA-2
Status	Beta — Production use at your own risk
Next Milestone	1.0.0-RC1 (Feb 3, 2026)
GA Target	Feb 24, 2026
License	Apache 2.0

Issue	Why it's a Feature
`[EPIC][SDK]: TypeScript SDK auto-generation`	Adds entirely new capability
`[FEATURE]: Add LangChain-based MCP Agent`	New integration component
`[EPIC][TESTING]: Automated MCP server compatibility regression suite`	Major new test automation infrastructure
`[FEATURE]: Export MCP session pool metrics to Prometheus`	New observability capability
`[EPIC][UI]: Notification center and alert management`	Significant new UI functionality
`[CHORE]: Implement GitHub Actions matrix for multi-Python testing`	Major automation feature (not just maintenance)

Issue	Why it's a Task
`[TESTING][SECURITY]: RBAC manual test plan`	Manual testing work (executing test plans)
`[TESTING][SECURITY]: Session management manual test plan`	Following documented test procedures
`[CHORE]: Remove unused PromptNotFoundError import`	Code cleanup
`[CLEANUP][SONAR]: Dead code - unused function in router`	Technical debt cleanup
`[CHORE]: Update Python dependencies`	Routine maintenance
`[DOCS]: Update API reference for new endpoints`	Documentation updates

Issue	Why it's a Bug
`[BUG]: anyio cancel scope spin loop causes 100% CPU`	Unexpected behavior causing system issues
`[BUG]: SSO admin tokens include teams key, preventing bypass`	Authentication not working correctly
`[BUG]: UI Export Config button missing after pagination`	UI element disappeared unexpectedly
`[BUG]: Multiple gateway import failing with unique constraint`	Feature not working as intended
`[SECURITY][SONAR]: ReDoS vulnerability in validation patterns`	Security defect

Label	Priority	Meaning	Examples
`MUST`	P1 🔴	Critical — Release blockers. Non-negotiable.	Security fixes, core functionality broken, blocking bugs
`SHOULD`	P2 🟠	Important — High value, include if possible.	Performance improvements, important features, UX fixes
`COULD`	P3 🟡	Nice-to-have — Minimal impact if deferred.	Minor enhancements, cleanup, nice-to-have features
`WOULD`	P4 🟢	Future — Not this release, backlog items.	Future ideas, low-priority enhancements

Milestone	Target Date	Theme	Status
Release 1.0.0-RC1	Feb 3, 2026	Security, Linting, Catalog, UI Polish	🔄 Active
Release 1.0.0-GA	Feb 24, 2026	Technical Debt, A2A, MCP Standard Sync	📋 Planned
Release 1.1.0	Mar 31, 2026	Technical Debt and Quality	📋 Planned
Release 1.2.0	Apr 28, 2026	Documentation, Bugfixes	📋 Planned
Release 1.3.0	May 26, 2026	New MCP Servers and Agents	📋 Planned
Release 1.4.0	Jun 22, 2026	Enterprise Features, Federation, Performance	📋 Planned
Release 1.5.0	Jul 20, 2026	Ecosystem Integrations, Observability, Plugin Marketplace	📋 Planned
Release 1.6.0	Aug 16, 2026	Collaboration, Workflow, Security Posture	📋 Planned

Label	Description
`bug`	Something isn't working
`enhancement`	New feature or improvement
`documentation`	Docs improvements
`testing`	Unit, E2E, manual, or automated testing
`manual-testing`	Manual test plans requiring human execution
`chore`	Maintenance, linting, dependency updates
`security`	Security improvements or fixes
`epic`	Large feature spanning multiple issues

Label	Description
`triage`	Awaiting review and prioritization
`planned`	Scheduled for a future release
`blocked`	Waiting on another issue/PR
`awaiting-user`	Needs feedback from reporter
`fixed`	Issue resolved (pending close)
`wontfix`	Will not be addressed
`duplicate`	Already tracked elsewhere

Label	Description
`python`	Python / FastAPI backend
`go`	Go programming
`rust`	Rust programming
`javascript` / `typescript`	JS/TS code
`frontend`	HTML, CSS, JavaScript UI
`java` / `haskell`	Other languages

Label	Description
`mcpgateway.translate`	stdio→HTTP translator
`mcpgateway.wrapper`	Gateway wrapper
`plugins`	Plugin framework
`ui`	Admin UI
`database`	Database layer
`helm`	Helm charts
`devops`	Containers, CI/CD, deployment
`cicd`	GitHub Actions
`rbac`	Role-based access control
`observability`	Logging, metrics, tracing

Label	Description
`mcp-protocol`	MCP specification alignment
`mcp-2025-06-18`	MCP 2025-06-18 spec
`a2a`	Agent-to-Agent protocol

Label	Description
`good first issue`	Great for newcomers!
`help wanted`	Extra attention needed
`priority`	High-priority queue
`sonar`	SonarQube findings
`experimental`	Experimental features

Looking for...	Filter
Beginner-friendly	`good first issue`
Needs help	`help wanted`
Bugs to fix	`bug`
Documentation	`documentation`
Critical items	`MUST`
Quick wins	`COULD` + `chore`
Security items	`security`
Needs triage	`triage`

Resource	What's There
README.md	Quick start, installation, configuration
Docs Site	Full documentation, tutorials, API reference
SECURITY.md	Security policies, hardening, vulnerability reporting
CONTRIBUTING.md	Contribution guidelines, code standards
CLAUDE.md	AI coding assistant guidelines
Architecture	ADRs, design decisions, roadmap
FAQ	Common questions answered

[README-FIRST]: Project Backlog & Issue Guide #2502

Description

[README-FIRST]: Project Backlog & Issue Guide

📋 Quick Links

🔒 Security Reporting

🚦 Project Status

🏷️ Issue Types: Feature vs Task vs Bug

✨ Feature (enhancement)

📋 Task (chore, testing, documentation)

🐛 Bug (bug)

Quick Decision Guide

🎯 MoSCoW Prioritization

📦 Release Roadmap

🏷️ Label Reference

Issue Type

Status

Technology

Component

Protocol

Special

🐛 How to File a Bug

✨ How to Request a Feature

🤝 Contributing

🔍 Finding Issues to Work On

📊 Backlog at a Glance

📚 Documentation Structure

❓ Questions?

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

✨ Feature (`enhancement`)

📋 Task (`chore`, `testing`, `documentation`)

🐛 Bug (`bug`)