learn-mcp-server 0.1.0__py3-none-any.whl

learn_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

learn_mcp_server/data/__init__.py

@@ -0,0 +1,15 @@
+from learn_mcp_server.data.concepts import CONCEPTS, LEARNING_MODULES
+from learn_mcp_server.data.configs import CONFIG_DOCS, DEBUG_GUIDES
+from learn_mcp_server.data.curriculum import CURRICULUMS
+from learn_mcp_server.data.examples import CODE_EXAMPLES
+from learn_mcp_server.data.practices import PRACTICE_TASKS
+
+__all__ = [
+    "CODE_EXAMPLES",
+    "CONCEPTS",
+    "CONFIG_DOCS",
+    "CURRICULUMS",
+    "DEBUG_GUIDES",
+    "LEARNING_MODULES",
+    "PRACTICE_TASKS",
+]

learn_mcp_server/data/concepts.py

@@ -0,0 +1,197 @@
+CONCEPTS = {
+    "mcp": """
+MCP，全称是 Model Context Protocol，中文可以理解为模型上下文协议。
+
+它的核心作用是让大模型应用能够用一种统一的方式连接外部工具、数据和提示词。
+
+MCP Server 不直接等于大模型，它只是给大模型应用提供可用能力。
+""",
+    "host": """
+Host 是 MCP 架构中的宿主应用。
+
+它通常是用户真正使用的应用，例如 AI 编程工具、聊天应用、IDE、桌面客户端等。
+""",
+    "client": """
+Client 是 Host 内部负责和 MCP Server 通信的组件。
+
+它负责发送初始化请求、获取能力清单、调用工具、读取资源和获取提示词。
+""",
+    "server": """
+Server 是 MCP 架构中提供能力的一方。
+
+MCP Server 可以提供 Tools、Resources 和 Prompts。
+""",
+    "tool": """
+Tool 是 MCP Server 暴露给模型调用的可执行能力。
+
+Tool 适合表示动作、计算、查询、生成、处理等操作。
+
+在 FastMCP 中，可以使用 @mcp.tool() 把一个 Python 函数注册成 MCP Tool。
+""",
+    "resource": """
+Resource 是 MCP Server 暴露出来的可读取上下文资源。
+
+Resource 更像文档、资料、文件、说明书、数据库记录等内容。
+""",
+    "prompt": """
+Prompt 是 MCP Server 提供的可复用提示词模板。
+
+Prompt 适合封装一段固定的任务说明，让用户或模型可以复用。
+
+在 FastMCP 中，可以使用 @mcp.prompt() 注册 Prompt。
+""",
+    "stdio": """
+stdio 是 MCP 的一种本地传输方式。
+
+它通过标准输入和标准输出传输 MCP 消息。
+
+stdio 模式下，不应该随便使用 print 输出普通日志，因为 stdout 是协议通信通道。
+""",
+    "streamable-http": """
+Streamable HTTP 是 MCP 的一种 HTTP 传输方式。
+
+它通常适合远程访问、Web 服务、长期运行的 MCP Server。
+""",
+    "json-rpc": """
+JSON-RPC 是一种基于 JSON 的远程过程调用格式。
+
+MCP 的消息通信基于 JSON-RPC 结构，常见字段包括 jsonrpc、id、method、params、result 和 error。
+""",
+    "resource-template": """
+Resource Template 是带参数的动态 Resource。
+
+它通过 URI 占位符把路径中的值映射到函数参数，例如 mcp://concepts/{name} 会把 name 传给对应函数。
+
+Resource Template 适合按名称、ID、路径或主题动态读取上下文内容。
+""",
+    "transport": """
+Transport 是 MCP Client 和 MCP Server 之间传输 JSON-RPC 消息的通道。
+
+常见 Transport 包括本地 stdio 和基于 HTTP 的 streamable-http。
+
+选择 Transport 时，要先判断 Server 是由 Host 启动，还是作为长期运行的服务被远程访问。
+""",
+    "sse": """
+SSE，全称是 Server-Sent Events，是一种服务端向客户端持续推送事件的 HTTP 技术。
+
+在 MCP 早期或部分生态里，SSE 曾经常被用来承载远程 MCP 通信。
+
+学习 SSE 的重点不是把它和 streamable-http 混为一谈，而是理解它解决的是“服务端持续发送消息”的问题。
+""",
+    "capability-negotiation": """
+能力协商是 MCP Client 和 MCP Server 在连接初始化阶段互相确认支持能力的过程。
+
+Client 会通过 initialize 等消息了解 Server 支持哪些 Tools、Resources、Prompts 或其他能力。
+
+能力协商的意义是让 Host 不需要猜测 Server 能做什么，而是通过协议清单发现可用能力。
+""",
+    "notification": """
+通知是 MCP 中不要求对方返回结果的协议消息。
+
+它适合表达状态变化、进度变化、资源变更等事件。
+
+和普通请求不同，通知通常没有 result，重点是让另一端知道某件事已经发生。
+""",
+    "sampling": """
+采样是 MCP 中让 Server 请求 Host 或模型生成内容的一类能力。
+
+它可以让某些 Server 在需要语言模型能力时，不直接内置模型，而是通过 Host 侧模型完成生成。
+
+学习采样时要注意权限边界：Server 不应该绕过 Host 直接滥用模型能力。
+""",
+    "roots": """
+根目录是 Host 告诉 MCP Server 的可访问工作区范围。
+
+它通常用于让 Server 知道哪些目录、项目或文件范围可以作为上下文来处理。
+
+根目录的意义是限制边界，避免 Server 在不了解上下文范围时访问不该访问的位置。
+""",
+    "elicitation": """
+Elicitation 是 MCP 中 Server 向 Host 请求用户补充信息的一类能力。
+
+它适合在工具调用或工作流继续之前，让用户确认、补充或选择必要信息。
+
+学习 elicitation 时要注意：Server 不能假装用户已经同意，应该由 Host 控制用户交互和授权边界。
+""",
+    "authorization": """
+Authorization 是 MCP 中围绕访问授权、身份和权限边界的设计。
+
+它用于帮助 Host 和 Server 明确谁能访问什么资源、什么时候需要用户同意，以及凭证不能被随意暴露。
+
+学习授权时，不要只看“能不能连上”，还要看最小权限、用户确认和凭证保护。
+""",
+    "security": """
+Security 是 MCP 项目必须持续考虑的安全边界。
+
+它包括工具调用前的用户确认、敏感数据保护、prompt injection 风险、权限最小化和不信任外部输入。
+
+学习 MCP 安全时，要把 Server 看成会接触真实文件、网络或凭证的组件，而不只是一个普通示例函数。
+""",
+    "tasks": """
+Tasks 是 MCP 中用于描述长时间运行任务的实验性方向。
+
+它适合表达需要持续跟踪、可能产生进度或结果更新的工作，而不是一次请求马上返回的简单 Tool 调用。
+
+学习 tasks 时，重点理解它和普通 Tool 的区别：Tool 偏即时调用，长时间运行任务更强调状态、进度和后续结果。
+""",
+    "config": """
+配置是 Host 发现和启动 MCP Server 的入口。
+
+stdio 配置通常依赖 command 和 args，由 Host 启动本地进程。
+
+streamable-http 配置通常依赖 url，由 Host 连接已经运行的 MCP 服务。
+""",
+    "debug": """
+Debug 是 MCP 项目开发中定位启动、注册、配置、传输和调用问题的过程。
+
+常见排查顺序是：先确认环境，再确认启动命令，再确认能力注册，最后确认 Host 是否重新加载配置。
+""",
+}
+
+LEARNING_MODULES = [
+    {
+        "name": "MCP 基础概念",
+        "topics": ["mcp", "host", "client", "server"],
+        "description": "理解 MCP 的整体架构和核心角色。",
+    },
+    {
+        "name": "MCP 原语",
+        "topics": ["tool", "resource", "prompt"],
+        "description": "学习 Tool、Resource、Prompt 的用途和区别。",
+    },
+    {
+        "name": "MCP 传输方式",
+        "topics": ["stdio", "streamable-http"],
+        "description": "学习 MCP Server 和 Client 之间如何通信。",
+    },
+    {
+        "name": "MCP 协议消息",
+        "topics": ["json-rpc"],
+        "description": "理解 MCP 底层消息格式和请求响应结构。",
+    },
+    {
+        "name": "MCP 进阶能力",
+        "topics": [
+            "sse",
+            "capability-negotiation",
+            "notification",
+            "sampling",
+            "roots",
+            "elicitation",
+            "tasks",
+        ],
+        "description": "理解 MCP 生态里更深入的通信、能力发现、通知、采样、用户交互和任务状态。",
+    },
+    {
+        "name": "MCP 安全与授权",
+        "topics": ["security", "authorization"],
+        "description": "学习 MCP 项目里的安全边界、用户确认、权限最小化和凭证保护。",
+    },
+    {
+        "name": "MCP 工程化实践",
+        "topics": ["resource-template", "config", "debug"],
+        "description": "学习动态资源、Host 配置和常见调试流程。",
+    },
+]
+
+__all__ = ["CONCEPTS", "LEARNING_MODULES"]

learn_mcp_server/data/configs.py

@@ -0,0 +1,142 @@
+CONFIG_DOCS = {
+    "stdio": """
+# stdio 配置
+
+stdio 配置适合本地 MCP Server。Host 会启动一个本地进程，并通过标准输入输出交换 MCP 消息。
+
+发布后推荐使用 uvx 运行。uvx 会为这个 MCP Server 创建隔离环境并自动安装依赖，不需要用户手动配置 Python 解释器路径。
+
+发布版示例：
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "learn-mcp-server==0.1.0",
+        "learn-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+本地开发示例：
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "E:\\\\SoftwareProject\\\\learn-mcp-server",
+        "learn-mcp-server"
+      ]
+    }
+  }
+}
+```
+""",
+    "streamable-http": """
+# streamable-http 配置
+
+streamable-http 配置适合已经通过 HTTP 运行的 MCP Server。
+
+示例：
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server-http": {
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
+""",
+    "local-vs-remote": """
+# 本地配置和远程配置
+
+本地 stdio 配置通常包含 command 和 args，由 Host 负责启动进程。
+
+给别人使用时，推荐 command 使用 uvx，并通过 --from 指定包名和版本。
+
+本地开发时，推荐 command 使用 uv，并通过 run --directory 指向项目目录。
+
+远程或 HTTP 配置通常包含 url，由 Host 连接已经运行的 MCP 服务。
+""",
+    "common-errors": """
+# 配置常见错误
+
+常见配置问题包括：
+
+1. command 没有使用 uvx，或者用户机器没有安装 uv
+2. uvx 的 --from 包名或版本号写错
+3. 本地开发配置中的 uv run --directory 路径写错
+4. stdio 配置中误写了 url
+5. streamable-http 配置中服务没有启动
+6. 修改配置后没有重启 Host
+""",
+}
+
+DEBUG_GUIDES = {
+    "stdio": """
+# stdio 调试
+
+stdio 模式通过标准输入和标准输出传输 MCP 协议消息。
+
+调试时要注意：
+
+1. 不要使用 print 输出普通日志
+2. stdout 是协议通道
+3. 普通日志应写入 stderr 或日志文件
+4. Host 修改配置后通常需要重启
+""",
+    "stdio-errors": """
+# stdio 错误
+
+stdio 常见错误包括：
+
+1. 使用 print 污染 stdout 协议通道
+2. Host 配置中的 command 没有指向 uvx 或 uv
+3. uvx 的 --from 包名或版本号不正确
+4. 本地开发配置中的 uv run --directory 路径不正确
+""",
+    "http-errors": """
+# HTTP 错误
+
+streamable-http 常见错误包括：
+
+1. MCP Server 没有启动
+2. url 没有指向 /mcp
+3. 端口被占用
+4. Host 无法访问对应地址
+""",
+    "config-errors": """
+# 配置错误
+
+配置常见错误包括：
+
+1. JSON 格式不合法
+2. mcpServers 字段缺失
+3. stdio 的 command 或 args 写错
+4. streamable-http 的 url 写错
+""",
+    "common-errors": """
+# 常见错误
+
+常见 MCP 调试问题包括：
+
+1. 用户机器没有安装 uv，或者 uvx 无法解析包名
+2. 启动命令路径写错
+3. 本地开发配置中的 --directory 不在期望目录
+4. 工具函数缺少类型注解
+5. Resource URI 写错
+""",
+}
+
+__all__ = ["CONFIG_DOCS", "DEBUG_GUIDES"]

learn_mcp_server/data/curriculum.py

@@ -0,0 +1,102 @@
+CURRICULUMS = {
+    "beginner": """
+# MCP Beginner 课程
+
+学习目标：
+用最短路径理解 MCP 是什么，并能运行、观察、调用一个最小 MCP Server。
+
+第 1 课：MCP、Host、Client、Server
+- 理解 MCP 不是模型本身，而是模型应用连接外部能力的协议。
+- 读取 mcp://docs/introduction 和 mcp://docs/architecture。
+- 练习 explain_concept("mcp") 和 get_concept_map()。
+
+第 2 课：Tool
+- 理解 Tool 是模型可以调用的动作。
+- 读取 mcp://docs/tools 和 mcp://examples/basic-tool。
+- 练习 get_practice_task("tool")，再用 check_answer 检查理解。
+
+第 3 课：Resource
+- 理解 Resource 是模型可以读取的上下文。
+- 读取 mcp://docs/resources 和 mcp://examples/basic-resource。
+- 对比 compare_concepts("tool", "resource")。
+
+第 4 课：Prompt
+- 理解 Prompt 是可复用任务模板。
+- 读取 mcp://docs/prompts 和 mcp://examples/basic-prompt。
+- 调用 explain_mcp_topic 观察 Prompt 返回结构。
+
+第 5 课：Inspector 和客户端验证
+- 使用 uv run fastmcp dev inspector src\\learn_mcp_server\\server.py 查看能力列表。
+- 运行 examples/client_test.py，确认 Tools、Resources、Prompts 都能被发现。
+""",
+    "intermediate": """
+# MCP Intermediate 课程
+
+学习目标：
+掌握动态资源、配置生成、传输方式和端到端 Client 调用流程。
+
+第 1 课：Resource Template
+- 理解 Resource Template 是带参数的动态 Resource。
+- 读取 mcp://docs/resource-template 和 mcp://examples/resource-template。
+- 练习 get_practice_task("resource-template")。
+
+第 2 课：Transport
+- 对比 stdio 和 streamable-http。
+- 读取 mcp://docs/stdio、mcp://docs/streamable-http 和 mcp://docs/config-local-vs-remote。
+- 调用 compare_local_and_remote_config()。
+
+第 3 课：Host 配置
+- 调用 generate_stdio_config(command, args) 生成本地配置。
+- 调用 generate_http_config(server_url) 生成 HTTP 配置。
+- 用 explain_config(config_text) 解释配置。
+
+第 4 课：端到端 Client
+- 读取 mcp://examples/end-to-end-client。
+- 理解 list_tools、list_resources、call_tool、read_resource、get_prompt 的顺序。
+
+第 5 课：JSON-RPC
+- 读取 mcp://docs/json-rpc。
+- 练习 get_practice_task("json-rpc")。
+""",
+    "advanced": """
+# MCP Advanced 课程
+
+学习目标：
+理解 MCP 进阶能力、边界和真实项目排查方式。
+
+第 1 课：能力协商
+- 理解 initialize 阶段如何发现 Server 能力。
+- 学习 capability-negotiation，知道 Host 为什么能列出工具、资源和 Prompt。
+
+第 2 课：通知
+- 学习 notification，理解不需要 result 的协议消息。
+- 区分请求响应和单向事件通知。
+
+第 3 课：sampling
+- 学习 sampling，理解 Server 请求 Host 侧模型生成内容的场景。
+- 重点关注权限边界和 Host 控制权。
+
+第 4 课：elicitation
+- 学习 elicitation，理解 Server 如何通过 Host 请求用户补充信息。
+- 重点区分“Server 需要信息”和“Host 负责用户交互”。
+
+第 5 课：roots
+- 学习 roots，理解 Host 提供给 Server 的工作区边界。
+- 思考为什么 Server 不应该默认拥有全盘访问范围。
+
+第 6 课：authorization 和 security
+- 学习授权、最小权限、用户确认和敏感数据保护。
+- 思考 Tool 访问文件、网络或凭证前应该满足哪些条件。
+
+第 7 课：tasks
+- 学习长时间运行任务的设计思路。
+- 区分一次性 Tool 调用和需要状态、进度、后续结果的任务。
+
+第 8 课：调试闭环
+- 调用 diagnose_issue 和 explain_error_message。
+- 练习 get_practice_task("debug")。
+- 按环境、启动命令、注册表、Host 重载、Client 调用顺序排查问题。
+""",
+}
+
+__all__ = ["CURRICULUMS"]

learn_mcp_server/data/examples.py

@@ -0,0 +1,135 @@
+CODE_EXAMPLES = {
+    "basic-tool": """
+# basic-tool
+
+下面是一个最小 MCP Tool 示例：
+
+```python
+@mcp.tool()
+def get_server_info() -> str:
+    return "learn-mcp-server"
+```
+
+这个示例说明：普通 Python 函数可以通过 @mcp.tool() 注册成模型可调用的 Tool。
+""",
+    "basic-resource": """
+# basic-resource
+
+下面是一个最小 MCP Resource 示例：
+
+```python
+@mcp.resource("mcp://docs/introduction")
+def get_docs_introduction() -> str:
+    return "MCP 入门文档"
+```
+
+这个示例说明：Resource 通过 URI 暴露可读取的上下文内容。
+""",
+    "resource-template": """
+# resource-template
+
+下面是一个最小 MCP Resource Template 示例：
+
+```python
+@mcp.resource("mcp://concepts/{name}")
+def get_concept_resource(name: str) -> str:
+    return f"概念名称：{name}"
+```
+
+这个示例说明：URI 中的 {name} 会映射到同名函数参数 name。
+""",
+    "basic-prompt": """
+# basic-prompt
+
+下面是一个最小 MCP Prompt 示例：
+
+```python
+@mcp.prompt()
+def explain_mcp_topic(topic: str, level: str) -> str:
+    return f"请用 {level} 水平解释 MCP 主题：{topic}"
+```
+
+这个示例说明：Prompt 适合封装可复用的任务提示词模板。
+""",
+    "tool-params": """
+# tool-params
+
+下面是一个带参数的 MCP Tool 示例：
+
+```python
+@mcp.tool()
+def explain_concept(concept: str) -> str:
+    return f"解释概念：{concept}"
+```
+
+这个示例说明：函数参数会成为 Tool 的输入 schema。
+""",
+    "async-tool": """
+# async-tool
+
+下面是一个异步 MCP Tool 示例：
+
+```python
+@mcp.tool()
+async def fetch_status(url: str) -> str:
+    return "ok"
+```
+
+这个示例说明：FastMCP 可以注册 async 函数。
+""",
+    "error-handling": """
+# error-handling
+
+下面是一个错误处理示例：
+
+```python
+@mcp.tool()
+def explain_concept(concept: str) -> str:
+    if not concept.strip():
+        raise ValueError("concept 不能为空")
+    return concept
+```
+
+这个示例说明：Tool 可以通过清晰的异常信息帮助调用方理解输入错误。
+""",
+    "end-to-end-client": """
+# end-to-end-client
+
+下面是一个端到端 FastMCP Client 示例，它会列出能力、调用 Tool、读取 Resource，并获取 Prompt：
+
+```python
+import asyncio
+
+from fastmcp import Client
+from learn_mcp_server.server import mcp
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        tools = await client.list_tools()
+        resources = await client.list_resources()
+        prompts = await client.list_prompts()
+
+        tool_result = await client.call_tool("explain_concept", {"concept": "tool"})
+        resource_result = await client.read_resource("mcp://docs/introduction")
+        prompt_result = await client.get_prompt(
+            "explain_mcp_topic",
+            {"topic": "resource", "level": "beginner"},
+        )
+
+    print([tool.name for tool in tools])
+    print([resource.uri for resource in resources])
+    print([prompt.name for prompt in prompts])
+    print(tool_result.data)
+    print(resource_result[0].text)
+    print(prompt_result.messages[0].content.text)
+
+
+asyncio.run(main())
+```
+
+这个示例说明：学习 MCP 时，不只要知道 Tool、Resource、Prompt 怎么写，还要知道 Client 如何发现并使用它们。
+""",
+}
+
+__all__ = ["CODE_EXAMPLES"]

learn_mcp_server/data/practices.py

@@ -0,0 +1,54 @@
+PRACTICE_TASKS = {
+    "tool": {
+        "title": "Tool 练习",
+        "task": "实现一个 get_server_info Tool，返回 Server 名称、用途和当前支持的能力。",
+        "keywords": ["tool", "@mcp.tool", "动作", "执行"],
+    },
+    "resource": {
+        "title": "Resource 练习",
+        "task": "实现一个 mcp://docs/introduction Resource，返回一段 MCP 入门文档。",
+        "keywords": ["resource", "@mcp.resource", "uri", "上下文"],
+    },
+    "prompt": {
+        "title": "Prompt 练习",
+        "task": "实现一个 explain_mcp_topic Prompt，根据主题和水平生成讲解提示词。",
+        "keywords": ["prompt", "@mcp.prompt", "模板", "提示词"],
+    },
+    "resource-template": {
+        "title": "Resource Template 练习",
+        "task": "实现一个 mcp://concepts/{name} Resource Template，根据 name 返回不同概念文档。",
+        "keywords": ["resource template", "@mcp.resource", "{name}", "动态资源", "uri"],
+    },
+    "transport": {
+        "title": "Transport 练习",
+        "task": "对比 stdio 和 streamable-http，说明它们分别适合什么运行场景。",
+        "keywords": ["transport", "stdio", "streamable-http", "通信"],
+    },
+    "json-rpc": {
+        "title": "JSON-RPC 练习",
+        "task": "写出一个 MCP 请求消息包含哪些关键字段，并解释 method、params、result、error 的作用。",
+        "keywords": ["json-rpc", "method", "params", "result", "error"],
+    },
+    "config": {
+        "title": "Config 练习",
+        "task": "分别生成一个 stdio 配置和一个 streamable-http 配置，并解释 command、args、url 的区别。",
+        "keywords": ["config", "mcpServers", "command", "args", "url"],
+    },
+    "elicitation": {
+        "title": "Elicitation 练习",
+        "task": "设计一个需要用户补充信息才能继续的 MCP 场景，说明 Server 应该请求什么、Host 应该如何让用户确认。",
+        "keywords": ["elicitation", "用户", "补充信息", "确认", "Host"],
+    },
+    "security": {
+        "title": "Security 练习",
+        "task": "列出一个 MCP Tool 访问本地文件或网络前需要做的安全检查，包括用户确认、最小权限和输入校验。",
+        "keywords": ["security", "授权", "用户确认", "最小权限", "输入校验"],
+    },
+    "debug": {
+        "title": "Debug 练习",
+        "task": "假设 Host 看不到工具，按环境、启动命令、注册表、Host 重载的顺序写出排查步骤。",
+        "keywords": ["debug", "环境", "启动", "注册", "Host"],
+    },
+}
+
+__all__ = ["PRACTICE_TASKS"]

learn_mcp_server/prompts/__init__.py

@@ -0,0 +1,3 @@
+from learn_mcp_server.prompts import learning_prompts
+
+__all__ = ["learning_prompts"]