From 4765d11e10f9cc4a74abab41dc8c96552ec7392b Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 11 Feb 2026 14:44:21 -0500 Subject: [PATCH] Add .gitignore, README.md, and other docs/* files with menu-linked template --- .gitignore | 6 +++ CONTRIBUTING.md | 68 ++++++++++++++++++++++++++++ README.md | 85 ++++++++++++++++++++++++++++++++++- docs/approaches.md | 8 ++++ docs/experimental-findings.md | 8 ++++ docs/open-questions.md | 8 ++++ docs/problem-statement.md | 8 ++++ docs/related-work.md | 8 ++++ docs/use-cases.md | 8 ++++ 9 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 docs/approaches.md create mode 100644 docs/experimental-findings.md create mode 100644 docs/open-questions.md create mode 100644 docs/problem-statement.md create mode 100644 docs/related-work.md create mode 100644 docs/use-cases.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..81308a8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +.claude/settings.local.json +.idea +.vscode +dist +node_modules +.DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c391d90 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing +[Problem Statement](docs/problem-statement.md) | +[Use Cases](docs/use-cases.md) | +[Approaches](docs/approaches.md) | +[Open Questions](docs/open-questions.md) | +[Experimental Findings](docs/experimental-findings.md) | +[Related Work](docs/related-work.md) | +Contributing +## How to Participate + +This Interest Group welcomes contributions from anyone interested in organization of MCP primitives. You can participate by: + +- Joining discussions in the [#primitive-grouping-ig](https://discord.com/channels/1358869848138059966/1425903819186770064) (info on joining the Discord server [here](https://modelcontextprotocol.io/community/communication#discord)) +- Opening or commenting on GitHub Discussions in this repo +- Sharing experimental findings from your own implementations +- Contributing to documentation and pattern evaluation + +## Communication Channels + +| Channel | Purpose | Response Expectation | +|:-------------------------------------------------------------------------------------------------------| :--- | :--- | +| [Discord #primitive-grouping-ig](https://discord.com/channels/1358869848138059966/1425903819186770064) | Quick questions, coordination, async discussion | Best effort | +| GitHub Discussions | Long-form technical proposals, experimental findings | Weekly triage | +| This repository | Living reference for approaches, findings, and decisions | Updated after meetings | + +## Meetings + +*To be scheduled* — likely biweekly working sessions once the group establishes momentum. + +Meeting norms: + +- Agendas published 24 hours in advance +- Notes published within 48 hours + +## Decision-Making + +As an Interest Group, we operate by **rough consensus** — we're exploring and recommending, not deciding. Outputs include: + +- Documented requirements and use cases +- Evaluated approaches with findings +- Recommendations to relevant WGs or as SEP proposals + +## Contribution Guidelines + +### Documenting Approaches and Findings + +When adding experimental findings or new approaches: + +- Include enough detail for others to reproduce or evaluate +- Note which clients and servers were tested +- Be explicit about what worked, what didn't, and what remains untested +- Attribute community input with GitHub handles and link to the source where possible + +### Community Input + +When adding quotes or input from community discussions: + +- Attribute to the contributor by name and GitHub handle +- Link to the original source (Discord thread, GitHub comment, etc.) where possible +- Present input as blockquotes to distinguish it from editorial content + +### Filing Issues + +Use GitHub Issues for: + +- Proposing new approaches or use cases +- Reporting gaps in documentation +- Tracking action items from meetings diff --git a/README.md b/README.md index 8718bfb..51d1515 100644 --- a/README.md +++ b/README.md @@ -1 +1,84 @@ -# experimental-ext-grouping +# Primitive Grouping Interest Group + +> ⚠️ **Experimental** — This repository is an incubation space for the Primitive Grouping Interest Group. Contents are exploratory and do not represent official MCP specifications or recommendations. + +## Mission + +This Interest Group explores how MCP Primitives (Tools, Resources, Prompts, Tasks) might be organized, beyond the flat lists that are maintained by the protocol, and how such organization might benefit both MCP servers and clients. + +## Scope + +### In Scope + +- **Requirements gathering:** Documenting use cases and constraints +- **Pattern exploration:** Testing and evaluating various approaches +- **Proof of concepts:** Maintaining a shared repo of reference implementations and experimental findings + +### Out of Scope + +- **Approving spec changes:** This IG does not have authority to approve protocol changes; recommendations flow through the SEP process +- **Implementation mandates:** We can document patterns but not require specific client or server behavior + +## Problem Statement + +Flat lists of MCP primitives can be long and cumbersome to work with. + +- **Context overload** — When loaded into the context of an LLM, a primitive list can overwhelm the model and lead to confusion and poor selection +- **Costly operation** - Long lists can consume many tokens, leading to higher costs for users. +- **Poor developer experience** — Lack of organizational tools for primitives makes them harder to manage and maintain + +See [problem-statement.md](docs/problem-statement.md) for full details. + +## Repository Contents + +| Document | Description | +| :--- | :--- | +| [Problem Statement](docs/problem-statement.md) | Current limitations and gaps | +| [Use Cases](docs/use-cases.md) | Key use cases driving this work | +| [Approaches](docs/approaches.md) | Approaches being explored (not mutually exclusive) | +| [Open Questions](docs/open-questions.md) | Unresolved questions with community input | +| [Experimental Findings](docs/experimental-findings.md) | Results from implementations and testing | +| [Related Work](docs/related-work.md) | SEPs, implementations, and external resources | +| [Contributing](CONTRIBUTING.md) | How to participate | + + +## Facilitators + +| Role | Name | Organization | GitHub | +| :--- |:------------|:-----------------------------------------------------------|:-----------------------------------------------| +| Facilitator | Tapan Chugh | CS PhD student at University of Washington | [@chughtapan](https://github.com/chughtapan) | +| Maintainer | Cliff Hall | Futurescale / MCP Maintainer | [@cliffhall](https://github.com/cliffhall) | +| Facilitator | Sam Morrow | Senior Software Engineer at GitHub | [@SamMorrowDrums](https://github.com/SamMorrowDrums) | + +## Lifecycle + +**Current Status: Active Exploration** + +### Graduation Criteria (IG → WG) + +This IG may propose becoming a Working Group if: + +- Clear consensus emerges on an approach requiring sustained spec work +- Cross-cutting coordination requires formal authority delegation +- At least two Core Maintainers sponsor WG formation + +### Retirement Criteria + +- Problem space resolved (conventions established, absorbed into other WGs) +- Insufficient participation to maintain momentum +- Community consensus that grouping doesn't belong in MCP protocol scope + +## Work Tracking + +| Item | Status | Champion | Notes | +|:-----------------------------------| :--- |:-----------------|:------------------------------------------------------------------| +| Requirements alignment | In Progress | All facilitators | Review approaches, identify common requirements and gaps | +| Experimental findings repo section | Proposed | TBD | Dedicated repo section for implementations and evaluation results | +| MCP Grouping Convention v0.1 | Proposed | TBD | Documented pattern (not spec) for grouping of primitives | + +## Success Criteria + +- **Short-term:** Documented consensus on requirements and evaluation of existing approaches +- **Medium-term:** Clear recommendation (convention vs. protocol extension vs. both) +- **Long-term:** Interoperable grouping convention across MCP servers and clients + diff --git a/docs/approaches.md b/docs/approaches.md new file mode 100644 index 0000000..7511a27 --- /dev/null +++ b/docs/approaches.md @@ -0,0 +1,8 @@ +# Approaches Being Explored +[Problem Statement](problem-statement.md) | +[Use Cases](use-cases.md) | +Approaches | +[Open Questions](open-questions.md) | +[Experimental Findings](experimental-findings.md) | +[Related Work](related-work.md) | +[Contributing](../CONTRIBUTING.md) diff --git a/docs/experimental-findings.md b/docs/experimental-findings.md new file mode 100644 index 0000000..4722f94 --- /dev/null +++ b/docs/experimental-findings.md @@ -0,0 +1,8 @@ +# Experimental Findings +[Problem Statement](problem-statement.md) | +[Use Cases](use-cases.md) | +[Approaches](approaches.md) | +[Open Questions](open-questions.md) | +Experimental Findings | +[Related Work](related-work.md) | +[Contributing](../CONTRIBUTING.md) diff --git a/docs/open-questions.md b/docs/open-questions.md new file mode 100644 index 0000000..20feacf --- /dev/null +++ b/docs/open-questions.md @@ -0,0 +1,8 @@ +# Open Questions +[Problem Statement](problem-statement.md) | +[Use Cases](use-cases.md) | +[Approaches](approaches.md) | +Open Questions | +[Experimental Findings](experimental-findings.md) | +[Related Work](related-work.md) | +[Contributing](../CONTRIBUTING.md) diff --git a/docs/problem-statement.md b/docs/problem-statement.md new file mode 100644 index 0000000..f033c0f --- /dev/null +++ b/docs/problem-statement.md @@ -0,0 +1,8 @@ +# Problem Statement +Problem Statement | +[Use Cases](use-cases.md) | +[Approaches](approaches.md) | +[Open Questions](open-questions.md) | +[Experimental Findings](experimental-findings.md) | +[Related Work](related-work.md) | +[Contributing](../CONTRIBUTING.md) diff --git a/docs/related-work.md b/docs/related-work.md new file mode 100644 index 0000000..1d87cd2 --- /dev/null +++ b/docs/related-work.md @@ -0,0 +1,8 @@ +# Related Work +[Problem Statement](problem-statement.md) | +[Use Cases](use-cases.md) | +[Approaches](approaches.md) | +[Open Questions](open-questions.md) | +[Experimental Findings](experimental-findings.md) | +Related Work | +[Contributing](../CONTRIBUTING.md) diff --git a/docs/use-cases.md b/docs/use-cases.md new file mode 100644 index 0000000..346fb28 --- /dev/null +++ b/docs/use-cases.md @@ -0,0 +1,8 @@ +# Use Cases +[Problem Statement](problem-statement.md) | +Use Cases | +[Approaches](approaches.md) | +[Open Questions](open-questions.md) | +[Experimental Findings](experimental-findings.md) | +[Related Work](related-work.md) | +[Contributing](../CONTRIBUTING.md)