From 95a616325ee53523c2aa2540e2975acdbd9065ae Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 15:05:27 +0000 Subject: [PATCH 01/13] Fix old `toolResult` format being used in TS exampel Resolves #80 --- docs/concepts/tools.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/concepts/tools.mdx b/docs/concepts/tools.mdx index 17cc10c..45eb4ec 100644 --- a/docs/concepts/tools.mdx +++ b/docs/concepts/tools.mdx @@ -73,7 +73,12 @@ Here's an example of implementing a basic tool in an MCP server: if (request.params.name === "calculate_sum") { const { a, b } = request.params.arguments; return { - toolResult: a + b + content: [ + { + type: "text", + text: String(a + b) + } + ] }; } throw new Error("Tool not found"); From 959e73dcf0eddb80bfa93b9537ba7f16ae15eeae Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 15:08:10 +0000 Subject: [PATCH 02/13] Fix Windows path backslash escaping Resolves #81 --- quickstart.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 3dc2c69..03e6013 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -453,7 +453,7 @@ In this case, we'll add our single weather server like so: "command": "uv", "args": [ "--directory", - "C:\\ABSOLUTE\PATH\TO\PARENT\FOLDER\weather", + "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather", "run", "weather" ] @@ -974,7 +974,7 @@ In this case, we'll add our single weather server like so: "weather": { "command": "node", "args": [ - "C:\\PATH\TO\PARENT\FOLDER\weather\build\index.js" + "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js" ] } } From c8bfb1473e6a409b830442f64411bc65b610fa3a Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 15:26:20 +0000 Subject: [PATCH 03/13] Add Development > Contributing page --- development/contributing.mdx | 10 ++++++++++ introduction.mdx | 2 +- mint.json | 13 ++++++++++++- 3 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 development/contributing.mdx diff --git a/development/contributing.mdx b/development/contributing.mdx new file mode 100644 index 0000000..52fb1f3 --- /dev/null +++ b/development/contributing.mdx @@ -0,0 +1,10 @@ +--- +title: Contributing +description: How to participate in Model Context Protocol development +--- + +We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/.github/blob/main/CONTRIBUTING.md) for details on how to submit changes. + +All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/.github/blob/main/CODE_OF_CONDUCT.md). + +For questions and discussions, please use [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions). diff --git a/introduction.mdx b/introduction.mdx index 86e692c..6e3f935 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -151,4 +151,4 @@ Dive deeper into MCP's core concepts and capabilities: ## Contributing -Want to contribute? Check out [@modelcontextprotocol](https://github.com/modelcontextprotocol) on GitHub to join our growing community of developers building with MCP. \ No newline at end of file +Want to contribute? Check out our [Contributing Guide](/development/contributing) to learn how you can help improve MCP. \ No newline at end of file diff --git a/mint.json b/mint.json index f5e0382..ffbf4fa 100644 --- a/mint.json +++ b/mint.json @@ -40,7 +40,12 @@ "navigation": [ { "group": "Get Started", - "pages": ["introduction", "quickstart", "examples", "clients"] + "pages": [ + "introduction", + "quickstart", + "examples", + "clients" + ] }, { "group": "Tutorials", @@ -61,6 +66,12 @@ "docs/concepts/sampling", "docs/concepts/transports" ] + }, + { + "group": "Development", + "pages": [ + "development/contributing" + ] } ], "footerSocials": { From 880471f47c6a09dc8519df06f9dec1072c936e6a Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 15:37:24 +0000 Subject: [PATCH 04/13] Document what we're thinking about in terms of roadmap --- development/roadmap.mdx | 57 +++++++++++++++++++++++++++++++++++++++++ mint.json | 1 + 2 files changed, 58 insertions(+) create mode 100644 development/roadmap.mdx diff --git a/development/roadmap.mdx b/development/roadmap.mdx new file mode 100644 index 0000000..7e335ab --- /dev/null +++ b/development/roadmap.mdx @@ -0,0 +1,57 @@ +--- +title: Roadmap +description: Our plans for evolving Model Context Protocol +--- + +The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction, though these may change significantly as the project develops. + +The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. + +We encourage community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts. + +## Remote MCP Support + +Our top priority is enabling [remote MCP connections](https://github.com/modelcontextprotocol/specification/discussions/102), allowing clients to securely connect to MCP servers over the internet. Key initiatives include: + +- [**Authentication & Authorization**](https://github.com/modelcontextprotocol/specification/discussions/64): Adding standardized auth capabilities, particularly focused on OAuth 2.0 support. + +- [**Service Discovery**](https://github.com/modelcontextprotocol/specification/discussions/69): Defining how clients can discover and connect to remote MCP servers, perhaps through a mechanism like a well known URI for MCP. + +- [**Stateless Operations**](https://github.com/modelcontextprotocol/specification/discussions/102): Ensuring MCP servers can operate in serverless environments, where they will need to be mostly stateless. + +## Reference Implementations + +To help developers build with MCP, we want to offer documentation for: + +- **Client Examples**: Comprehensive reference client implementation(s), demonstrating all protocol features +- **Protocol Drafting**: Streamlined process for proposing and incorporating new protocol features + +## Distribution & Discovery + +Looking ahead, we're exploring ways to make MCP servers more accessible. Some areas we may investigate include: + +- **Package Management**: Standardized packaging format for MCP servers +- **Installation Tools**: Simplified server installation across MCP clients +- **Sandboxing**: Improved security through server isolation +- **Server Registry**: A common directory for discovering available MCP servers + +## Agent Support + +We're expanding MCP's capabilities for [complex agentic workflows](https://github.com/modelcontextprotocol/specification/discussions/111), particularly focusing on: + +- [**Hierarchical Agent Systems**](https://github.com/modelcontextprotocol/specification/discussions/94): Improved support for trees of agents through namespacing and topology awareness. + +- [**Interactive Workflows**](https://github.com/modelcontextprotocol/specification/issues/97): Better handling of user permissions and information requests across agent hierarchies, and ways to send output to users instead of models. + +- [**Streaming Results**](https://github.com/modelcontextprotocol/specification/issues/117): Real-time updates from long-running agent operations. + +## Broader Ecosystem + +We're also invested in: + +- **Community-Led Standards Development**: Fostering a collaborative ecosystem where all AI providers can help shape MCP as an open standard through equal participation and shared governance, ensuring it meets the needs of diverse AI applications and use cases. +- [**Additional Modalities**](https://github.com/modelcontextprotocol/specification/discussions/88): Expanding beyond text to support audio, video, and other formats. + +## Get Involved + +We welcome community participation in shaping MCP's future. Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to join the conversation and contribute your ideas. diff --git a/mint.json b/mint.json index ffbf4fa..93fb64b 100644 --- a/mint.json +++ b/mint.json @@ -70,6 +70,7 @@ { "group": "Development", "pages": [ + "development/roadmap", "development/contributing" ] } From cdbe3591e352a21e8d60d43b8acf4462a4054560 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 16:12:56 +0000 Subject: [PATCH 05/13] Clarify this is H1 2025 --- development/roadmap.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/development/roadmap.mdx b/development/roadmap.mdx index 7e335ab..2e8e087 100644 --- a/development/roadmap.mdx +++ b/development/roadmap.mdx @@ -1,9 +1,9 @@ --- title: Roadmap -description: Our plans for evolving Model Context Protocol +description: Our plans for evolving Model Context Protocol (H1 2025) --- -The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction, though these may change significantly as the project develops. +The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction for **the first half of 2025**, though these may change significantly as the project develops. The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. From 4219dbafb2b19f272d6d8d75ef394e639bcee08b Mon Sep 17 00:00:00 2001 From: Zach Caceres Date: Tue, 17 Dec 2024 12:23:52 -0700 Subject: [PATCH 06/13] Update debugging.mdx --- docs/tools/debugging.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tools/debugging.mdx b/docs/tools/debugging.mdx index 6161a13..c4b47b2 100644 --- a/docs/tools/debugging.mdx +++ b/docs/tools/debugging.mdx @@ -105,6 +105,7 @@ Common initialization problems: - Incorrect server executable path - Missing required files - Permission problems + - Try using an absolute path for `command` 2. **Configuration Errors** - Invalid JSON syntax From 9031824639e20e154e514b6da81a923defdc4593 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 20:10:47 +0000 Subject: [PATCH 07/13] Apply suggestions from code review Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com> --- development/roadmap.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/development/roadmap.mdx b/development/roadmap.mdx index 2e8e087..0b1cbf4 100644 --- a/development/roadmap.mdx +++ b/development/roadmap.mdx @@ -15,7 +15,7 @@ Our top priority is enabling [remote MCP connections](https://github.com/modelco - [**Authentication & Authorization**](https://github.com/modelcontextprotocol/specification/discussions/64): Adding standardized auth capabilities, particularly focused on OAuth 2.0 support. -- [**Service Discovery**](https://github.com/modelcontextprotocol/specification/discussions/69): Defining how clients can discover and connect to remote MCP servers, perhaps through a mechanism like a well known URI for MCP. +- [**Service Discovery**](https://github.com/modelcontextprotocol/specification/discussions/69): Defining how clients can discover and connect to remote MCP servers. - [**Stateless Operations**](https://github.com/modelcontextprotocol/specification/discussions/102): Ensuring MCP servers can operate in serverless environments, where they will need to be mostly stateless. @@ -51,6 +51,7 @@ We're also invested in: - **Community-Led Standards Development**: Fostering a collaborative ecosystem where all AI providers can help shape MCP as an open standard through equal participation and shared governance, ensuring it meets the needs of diverse AI applications and use cases. - [**Additional Modalities**](https://github.com/modelcontextprotocol/specification/discussions/88): Expanding beyond text to support audio, video, and other formats. +- [**Standardization**] Considering standardization through a standardization body. ## Get Involved From 4270ebbff37f13343fe46acb67d7aff8a337c3df Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 17 Dec 2024 20:14:09 +0000 Subject: [PATCH 08/13] Address other review comments --- development/roadmap.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/development/roadmap.mdx b/development/roadmap.mdx index 0b1cbf4..4e4649c 100644 --- a/development/roadmap.mdx +++ b/development/roadmap.mdx @@ -5,7 +5,7 @@ description: Our plans for evolving Model Context Protocol (H1 2025) The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and future direction for **the first half of 2025**, though these may change significantly as the project develops. -The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. +The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an _exhaustive_ list; we may incorporate work that isn't mentioned here. We encourage community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts. @@ -17,7 +17,7 @@ Our top priority is enabling [remote MCP connections](https://github.com/modelco - [**Service Discovery**](https://github.com/modelcontextprotocol/specification/discussions/69): Defining how clients can discover and connect to remote MCP servers. -- [**Stateless Operations**](https://github.com/modelcontextprotocol/specification/discussions/102): Ensuring MCP servers can operate in serverless environments, where they will need to be mostly stateless. +- [**Stateless Operations**](https://github.com/modelcontextprotocol/specification/discussions/102): Thinking about whether MCP could encompass serverless environments too, where they will need to be mostly stateless. ## Reference Implementations From 3fc5423ea4c24a8f098da6f1b048f1df6058026a Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Tue, 17 Dec 2024 15:27:25 -0500 Subject: [PATCH 09/13] docs: Add LibreChat Client --- clients.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/clients.mdx b/clients.mdx index facc8a7..594a8ad 100644 --- a/clients.mdx +++ b/clients.mdx @@ -16,6 +16,7 @@ This page provides an overview of applications that support the Model Context Pr | [Continue][Continue] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features | | [GenAIScript][GenAIScript] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. | | [Cline][Cline] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. | +| [LibreChat][LibreChat] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents | [Claude]: https://claude.ai/download [Zed]: https://zed.dev @@ -24,6 +25,7 @@ This page provides an overview of applications that support the Model Context Pr [Continue]: https://github.com/continuedev/continue [GenAIScript]: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/ [Cline]: https://github.com/cline/cline +[LibreChat]: https://github.com/danny-avila/LibreChat [Resources]: https://modelcontextprotocol.io/docs/concepts/resources [Prompts]: https://modelcontextprotocol.io/docs/concepts/prompts @@ -95,6 +97,15 @@ Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft - Share custom MCP servers Cline creates with others via the `~/Documents/Cline/MCP` directory - Displays configured MCP servers along with their tools, resources, and any error logs +### LibreChat +[LibreChat](https://github.com/danny-avila/LibreChat) is an open-source, customizable AI chat UI that supports multiple AI providers, now including MCP integration. + +**Key features:** +- Extend current tool ecosystem, including [Code Interpreter](https://www.librechat.ai/docs/features/code_interpreter) and Image generation tools, through MCP servers +- Add tools to customizable [Agents](https://www.librechat.ai/docs/features/agents), using a variety of LLMs from top providers +- Open-source and self-hostable, with secure multi-user support +- Future roadmap includes expanded MCP feature support + ## Adding MCP support to your application If you've added MCP support to your application, we encourage you to submit a pull request to add it to this list. MCP integration can provide your users with powerful contextual AI capabilities and make your application part of the growing MCP ecosystem. From e72db76895525347af2d4d4eed3da80cb3958745 Mon Sep 17 00:00:00 2001 From: Sergey Ignatov Date: Tue, 17 Dec 2024 23:15:38 +0100 Subject: [PATCH 10/13] add kotlin sdk --- mint.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/mint.json b/mint.json index f5e0382..58ab593 100644 --- a/mint.json +++ b/mint.json @@ -31,6 +31,11 @@ "icon": "square-js", "url": "https://github.com/modelcontextprotocol/typescript-sdk" }, + { + "name": "Kotlin SDK", + "icon": "square-k", + "url": "https://github.com/modelcontextprotocol/kotlin-sdk" + }, { "name": "Specification", "icon": "book", From 6883255ab04df27b94b318286f650bb79ab33a52 Mon Sep 17 00:00:00 2001 From: David Soria Parra Date: Wed, 18 Dec 2024 11:53:26 +0000 Subject: [PATCH 11/13] Update roots.mdx to clarify that roots can be any URI --- docs/concepts/roots.mdx | 79 +++++++++++++++++++++++++++++++++++++++++ mint.json | 1 + 2 files changed, 80 insertions(+) create mode 100644 docs/concepts/roots.mdx diff --git a/docs/concepts/roots.mdx b/docs/concepts/roots.mdx new file mode 100644 index 0000000..e8d7267 --- /dev/null +++ b/docs/concepts/roots.mdx @@ -0,0 +1,79 @@ +--- +title: "Roots" +description: "Understanding roots in MCP" +--- + +Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations. + +## What are Roots? + +A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs. + +For example, roots could be: + +``` +file:///home/user/projects/myapp +https://api.example.com/v1 +``` + +## Why Use Roots? + +Roots serve several important purposes: + +1. **Guidance**: They inform servers about relevant resources and locations +2. **Clarity**: Roots make it clear which resources are part of your workspace +3. **Organization**: Multiple roots let you work with different resources simultaneously + +## How Roots Work + +When a client supports roots, it: + +1. Declares the `roots` capability during connection +2. Provides a list of suggested roots to the server +3. Notifies the server when roots change (if supported) + +While roots are informational and not strictly enforcing, servers should: + +1. Respect the provided roots +2. Use root URIs to locate and access resources +3. Prioritize operations within root boundaries + +## Common Use Cases + +Roots are commonly used to define: + +- Project directories +- Repository locations +- API endpoints +- Configuration locations +- Resource boundaries + +## Best Practices + +When working with roots: + +1. Only suggest necessary resources +2. Use clear, descriptive names for roots +3. Monitor root accessibility +4. Handle root changes gracefully + +## Example + +Here's how a typical MCP client might expose roots: + +```json +{ + "roots": [ + { + "uri": "file:///home/user/projects/frontend", + "name": "Frontend Repository" + }, + { + "uri": "https://api.example.com/v1", + "name": "API Endpoint" + } + ] +} +``` + +This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated. \ No newline at end of file diff --git a/mint.json b/mint.json index 1f47020..d5c63fd 100644 --- a/mint.json +++ b/mint.json @@ -58,6 +58,7 @@ "docs/concepts/prompts", "docs/concepts/tools", "docs/concepts/sampling", + "docs/concepts/roots", "docs/concepts/transports" ] } From 52ca5abdea2f01337ce3bb364184bc90d03c8018 Mon Sep 17 00:00:00 2001 From: Jonas Helming Date: Thu, 19 Dec 2024 13:16:03 +0100 Subject: [PATCH 12/13] Add Theia AI and Theia IDE as a client fixed #89 Signed-off-by: Jonas Helming --- clients.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/clients.mdx b/clients.mdx index 594a8ad..ca6dac2 100644 --- a/clients.mdx +++ b/clients.mdx @@ -17,6 +17,7 @@ This page provides an overview of applications that support the Model Context Pr | [GenAIScript][GenAIScript] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. | | [Cline][Cline] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. | | [LibreChat][LibreChat] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents | +| [TheiaAI/TheiaIDE][TheiaAI/TheiaIDE] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents in Theia AI and the AI-powered Theia IDE | [Claude]: https://claude.ai/download [Zed]: https://zed.dev @@ -26,6 +27,7 @@ This page provides an overview of applications that support the Model Context Pr [GenAIScript]: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/ [Cline]: https://github.com/cline/cline [LibreChat]: https://github.com/danny-avila/LibreChat +[TheiaAI/TheiaIDE]: https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/ [Resources]: https://modelcontextprotocol.io/docs/concepts/resources [Prompts]: https://modelcontextprotocol.io/docs/concepts/prompts @@ -106,6 +108,20 @@ Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft - Open-source and self-hostable, with secure multi-user support - Future roadmap includes expanded MCP feature support +### TheiaAI/TheiaIDE +[Theia AI](https://eclipsesource.com/blogs/2024/10/07/introducing-theia-ai/) is a framework for building AI-enhanced tools and IDEs. The [AI-powered Theia IDE](https://eclipsesource.com/blogs/2024/10/08/introducting-ai-theia-ide/) is an open and flexible development environment built on Theia AI. + +**Key features:** +- **Tool Integration**: Theia AI enables AI agents, including those in the Theia IDE, to utilize MCP servers for seamless tool interaction. +- **Customizable Prompts**: The Theia IDE allows users to define and adapt prompts, dynamically integrating MCP servers for tailored workflows. +- **Custom agents**: The Theia IDE supports creating custom agents that leverage MCP capabilities, enabling users to design dedicated workflows on the fly. + +Theia AI and Theia IDE's MCP integration provide users with flexibility, making them powerful platforms for exploring and adapting MCP. + +**Learn more:** +- [Theia IDE and Theia AI MCP Announcement](https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/) +- [Download the AI-powered Theia IDE](https://theia-ide.org/) + ## Adding MCP support to your application If you've added MCP support to your application, we encourage you to submit a pull request to add it to this list. MCP integration can provide your users with powerful contextual AI capabilities and make your application part of the growing MCP ecosystem. From b07b6ebcbd5abd56b40f037c132a79d9edf993e0 Mon Sep 17 00:00:00 2001 From: David Soria Parra Date: Wed, 18 Dec 2024 12:02:56 +0000 Subject: [PATCH 13/13] docs: Add working directory documentation (#74) --- docs/tools/debugging.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/tools/debugging.mdx b/docs/tools/debugging.mdx index c4b47b2..18ca18e 100644 --- a/docs/tools/debugging.mdx +++ b/docs/tools/debugging.mdx @@ -80,6 +80,23 @@ Use the Network panel to inspect: ## Common issues +### Working directory + +When using MCP servers with Claude Desktop: + +- The working directory for servers launched via `claude_desktop_config.json` may be undefined (like `/` on macOS) since Claude Desktop could be started from anywhere +- Always use absolute paths in your configuration and `.env` files to ensure reliable operation +- For testing servers directly via command line, the working directory will be where you run the command + +For example in `claude_desktop_config.json`, use: +```json +{ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"] +} +``` +Instead of relative paths like `./data` + ### Environment variables MCP servers inherit only a subset of environment variables automatically, like `USER`, `HOME`, and `PATH`.