learn-mcp-server 0.1.0__tar.gz

learn_mcp_server-0.1.0/.env.example

@@ -0,0 +1,5 @@
+LEARN_MCP_TRANSPORT=stdio
+
+# Supported values:
+# - stdio
+# - streamable-http

learn_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.env
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.idea/
+.DS_Store
+dist/
+*.egg-info/

learn_mcp_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

learn_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TangRuoJie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

learn_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: learn-mcp-server
+Version: 0.1.0
+Summary: A learning MCP server built with FastMCP.
+Project-URL: Homepage, https://github.com/TangRj-Git/learn-mcp-server
+Project-URL: Repository, https://github.com/TangRj-Git/learn-mcp-server
+Project-URL: Issues, https://github.com/TangRj-Git/learn-mcp-server/issues
+Author: TangRuoJie
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastmcp,learning,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Requires-Dist: fastmcp
+Description-Content-Type: text/markdown
+
+# learn-mcp-server
+
+`learn-mcp-server` 是一个使用 **FastMCP** 编写的 MCP 学习型 Server。它既是一个可以运行的 MCP Server，也是一个用于学习 MCP 项目结构、Tool、Resource、Resource Template、Prompt、配置和调试流程的教学示例。
+
+这个仓库的根目录 README 只保留项目介绍、安装运行、Host 配置和常用命令。更完整的需求设计、开发路线和模块拆分说明已经移动到 [docs/project-design-and-roadmap.md](docs/project-design-and-roadmap.md)。
+
+## 功能
+
+当前版本提供：
+
+- MCP 核心概念讲解
+- FastMCP Tool / Resource / Resource Template / Prompt 示例
+- 学习路线、课程资源和练习任务
+- stdio 与 streamable-http 配置说明
+- 常见错误诊断和调试建议
+- FastMCP Client 集成验证脚本
+
+当前注册能力：
+
+```text
+Tools: 20 个
+Resources: 39 个
+Resource Templates: 5 个
+Prompts: 5 个
+```
+
+## 环境要求
+
+推荐使用 `uv` 管理项目环境和运行命令。
+
+```powershell
+uv --version
+```
+
+如果没有安装 `uv`，Windows PowerShell 可以使用：
+
+```powershell
+irm https://astral.sh/uv/install.ps1 | iex
+```
+
+项目 Python 版本由 [.python-version](.python-version) 固定为：
+
+```text
+3.10
+```
+
+## 安装依赖
+
+在项目根目录执行：
+
+```powershell
+uv sync
+```
+
+## 运行测试
+
+```powershell
+uv run pytest -q
+```
+
+## 本地客户端验证
+
+```powershell
+uv run python examples\client_test.py
+```
+
+该脚本会列出当前 MCP Server 暴露的 Tools、Resources、Resource Templates 和 Prompts，并调用 `get_server_info` 做一次基本验证。
+
+## Inspector 调试
+
+Windows 下建议使用正斜杠绝对路径，并显式指定 `server.py` 里的 `mcp` 对象：
+
+```powershell
+uv run fastmcp dev inspector --no-reload E:/SoftwareProject/learn-mcp-server/src/learn_mcp_server/server.py:mcp
+```
+
+如果换成你自己的项目路径，也保持 `/`，不要写成 `E:\...`。反斜杠路径在 Inspector 的 URL 转换过程中可能被错误解析。
+
+Inspector 连接成功后，可以在页面里点击 `List Resources`、`List Templates`、`Tools`、`Prompts` 查看当前 MCP Server 暴露的能力。
+
+## stdio 配置
+
+### 发布后给别人使用
+
+发布到 PyPI 后，推荐让 Host 使用 `uvx` 启动。`uvx` 会创建隔离环境并自动安装依赖，使用者不需要手动配置 Python 解释器路径。
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "learn-mcp-server==0.1.0",
+        "learn-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+示例文件见 [examples/stdio_config.json](examples/stdio_config.json)。
+
+### 本地开发使用
+
+如果还没有发布到 PyPI，或者想让 Host 直接使用当前工作区代码，可以使用 `uv run --directory`：
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "E:\\SoftwareProject\\learn-mcp-server",
+        "learn-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+把 `--directory` 后面的路径替换成你本机项目根目录。
+
+## streamable-http 运行
+
+PowerShell：
+
+```powershell
+$env:LEARN_MCP_TRANSPORT="streamable-http"
+uv run learn-mcp-server
+```
+
+默认地址：
+
+```text
+http://127.0.0.1:8000/mcp
+```
+
+对应 Host 配置示例见 [examples/streamable_http_config.json](examples/streamable_http_config.json)。
+
+恢复 stdio：
+
+```powershell
+Remove-Item Env:\LEARN_MCP_TRANSPORT
+```
+
+## 常用命令
+
+```powershell
+uv sync
+uv run pytest -q
+uv run python examples\client_test.py
+uv run fastmcp dev inspector --no-reload E:/SoftwareProject/learn-mcp-server/src/learn_mcp_server/server.py:mcp
+uv build
+```
+
+## 项目结构
+
+```text
+learn-mcp-server/
+├── README.md
+├── pyproject.toml
+├── uv.lock
+├── .python-version
+├── docs/
+│   └── project-design-and-roadmap.md
+├── examples/
+│   ├── client_test.py
+│   ├── stdio_config.json
+│   └── streamable_http_config.json
+├── src/
+│   └── learn_mcp_server/
+│       ├── server.py
+│       ├── registry.py
+│       ├── settings.py
+│       ├── data/
+│       ├── prompts/
+│       ├── resources/
+│       ├── tools/
+│       └── utils/
+└── tests/
+```
+
+## 入口说明
+
+- [src/learn_mcp_server/server.py](src/learn_mcp_server/server.py)：创建 FastMCP 实例并启动服务
+- [src/learn_mcp_server/registry.py](src/learn_mcp_server/registry.py)：集中注册 Tools、Resources、Resource Templates 和 Prompts
+- [src/learn_mcp_server/settings.py](src/learn_mcp_server/settings.py)：运行配置和 transport 选择
+- [examples/client_test.py](examples/client_test.py)：本地 FastMCP Client 验证脚本
+- [docs/project-design-and-roadmap.md](docs/project-design-and-roadmap.md)：完整项目需求、设计和开发路线
+
+## 打包
+
+```powershell
+uv build
+```
+
+构建产物会生成到 `dist/`，该目录不会提交到 Git。
+
+## 发布后运行
+
+发布到 PyPI 后，可以直接用：
+
+```powershell
+uvx --from learn-mcp-server==0.1.0 learn-mcp-server
+```
+
+这也是推荐写入 MCP Host 配置的运行方式。

learn_mcp_server-0.1.0/README.md

@@ -0,0 +1,210 @@
+# learn-mcp-server
+
+`learn-mcp-server` 是一个使用 **FastMCP** 编写的 MCP 学习型 Server。它既是一个可以运行的 MCP Server，也是一个用于学习 MCP 项目结构、Tool、Resource、Resource Template、Prompt、配置和调试流程的教学示例。
+
+这个仓库的根目录 README 只保留项目介绍、安装运行、Host 配置和常用命令。更完整的需求设计、开发路线和模块拆分说明已经移动到 [docs/project-design-and-roadmap.md](docs/project-design-and-roadmap.md)。
+
+## 功能
+
+当前版本提供：
+
+- MCP 核心概念讲解
+- FastMCP Tool / Resource / Resource Template / Prompt 示例
+- 学习路线、课程资源和练习任务
+- stdio 与 streamable-http 配置说明
+- 常见错误诊断和调试建议
+- FastMCP Client 集成验证脚本
+
+当前注册能力：
+
+```text
+Tools: 20 个
+Resources: 39 个
+Resource Templates: 5 个
+Prompts: 5 个
+```
+
+## 环境要求
+
+推荐使用 `uv` 管理项目环境和运行命令。
+
+```powershell
+uv --version
+```
+
+如果没有安装 `uv`，Windows PowerShell 可以使用：
+
+```powershell
+irm https://astral.sh/uv/install.ps1 | iex
+```
+
+项目 Python 版本由 [.python-version](.python-version) 固定为：
+
+```text
+3.10
+```
+
+## 安装依赖
+
+在项目根目录执行：
+
+```powershell
+uv sync
+```
+
+## 运行测试
+
+```powershell
+uv run pytest -q
+```
+
+## 本地客户端验证
+
+```powershell
+uv run python examples\client_test.py
+```
+
+该脚本会列出当前 MCP Server 暴露的 Tools、Resources、Resource Templates 和 Prompts，并调用 `get_server_info` 做一次基本验证。
+
+## Inspector 调试
+
+Windows 下建议使用正斜杠绝对路径，并显式指定 `server.py` 里的 `mcp` 对象：
+
+```powershell
+uv run fastmcp dev inspector --no-reload E:/SoftwareProject/learn-mcp-server/src/learn_mcp_server/server.py:mcp
+```
+
+如果换成你自己的项目路径，也保持 `/`，不要写成 `E:\...`。反斜杠路径在 Inspector 的 URL 转换过程中可能被错误解析。
+
+Inspector 连接成功后，可以在页面里点击 `List Resources`、`List Templates`、`Tools`、`Prompts` 查看当前 MCP Server 暴露的能力。
+
+## stdio 配置
+
+### 发布后给别人使用
+
+发布到 PyPI 后，推荐让 Host 使用 `uvx` 启动。`uvx` 会创建隔离环境并自动安装依赖，使用者不需要手动配置 Python 解释器路径。
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "learn-mcp-server==0.1.0",
+        "learn-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+示例文件见 [examples/stdio_config.json](examples/stdio_config.json)。
+
+### 本地开发使用
+
+如果还没有发布到 PyPI，或者想让 Host 直接使用当前工作区代码，可以使用 `uv run --directory`：
+
+```json
+{
+  "mcpServers": {
+    "learn-mcp-server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "E:\\SoftwareProject\\learn-mcp-server",
+        "learn-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+把 `--directory` 后面的路径替换成你本机项目根目录。
+
+## streamable-http 运行
+
+PowerShell：
+
+```powershell
+$env:LEARN_MCP_TRANSPORT="streamable-http"
+uv run learn-mcp-server
+```
+
+默认地址：
+
+```text
+http://127.0.0.1:8000/mcp
+```
+
+对应 Host 配置示例见 [examples/streamable_http_config.json](examples/streamable_http_config.json)。
+
+恢复 stdio：
+
+```powershell
+Remove-Item Env:\LEARN_MCP_TRANSPORT
+```
+
+## 常用命令
+
+```powershell
+uv sync
+uv run pytest -q
+uv run python examples\client_test.py
+uv run fastmcp dev inspector --no-reload E:/SoftwareProject/learn-mcp-server/src/learn_mcp_server/server.py:mcp
+uv build
+```
+
+## 项目结构
+
+```text
+learn-mcp-server/
+├── README.md
+├── pyproject.toml
+├── uv.lock
+├── .python-version
+├── docs/
+│   └── project-design-and-roadmap.md
+├── examples/
+│   ├── client_test.py
+│   ├── stdio_config.json
+│   └── streamable_http_config.json
+├── src/
+│   └── learn_mcp_server/
+│       ├── server.py
+│       ├── registry.py
+│       ├── settings.py
+│       ├── data/
+│       ├── prompts/
+│       ├── resources/
+│       ├── tools/
+│       └── utils/
+└── tests/
+```
+
+## 入口说明
+
+- [src/learn_mcp_server/server.py](src/learn_mcp_server/server.py)：创建 FastMCP 实例并启动服务
+- [src/learn_mcp_server/registry.py](src/learn_mcp_server/registry.py)：集中注册 Tools、Resources、Resource Templates 和 Prompts
+- [src/learn_mcp_server/settings.py](src/learn_mcp_server/settings.py)：运行配置和 transport 选择
+- [examples/client_test.py](examples/client_test.py)：本地 FastMCP Client 验证脚本
+- [docs/project-design-and-roadmap.md](docs/project-design-and-roadmap.md)：完整项目需求、设计和开发路线
+
+## 打包
+
+```powershell
+uv build
+```
+
+构建产物会生成到 `dist/`，该目录不会提交到 Git。
+
+## 发布后运行
+
+发布到 PyPI 后，可以直接用：
+
+```powershell
+uvx --from learn-mcp-server==0.1.0 learn-mcp-server
+```
+
+这也是推荐写入 MCP Host 配置的运行方式。