Markdown规范MCP服务器
该项目提供了一种简单、， 只读的 MCP（模型上下文协议）服务器，用于向LLM提供本地标记文档。它是使用 fastmcp 图书馆。
服务器提供工具 list_specs, read_spec，以及 search_specs 从本地目录，但它不支持创建、编辑或删除文件。这使得它成为一种安全的方式，为模型提供对本地文档语料库的访问。
先决条件
- Python 3.13或更新版本
uv包管理器
安装
- 安装项目依赖关系：
此项目使用 uv 用于依赖性管理。运行以下命令将安装中列出的所有依赖项 pyproject.toml 并创建一个命令行脚本来运行服务器。
uv pip install .配置
可以通过设置环境变量来定制服务器的行为。
SPECS_DIR：指定所有与规范相关的操作的根目录。如果未设置此变量，服务器将默认使用“specs”目录。两者list_specs和read_spec工具将解析相对于此基本路径的文件和目录路径。
对于高级配置，您可以修改 src/config.py 文件，但建议使用环境变量。
运行服务器
您可以在两种模式下运行服务器： run 用于生产/消费和 dev 用于开发和测试。
运行模式
此模式用于运行Gemini CLI使用的服务器。安装后，您可以使用 mdspec 命令。
mdspec服务器现在将使用运行 stdio 作为运输机制。
开发模式
此模式启动MCP检查器，这是一个基于web的UI，允许对MCP服务器提供的工具进行交互式测试。
fastmcp dev src/main.py --ui-port="9080" --server-port="5080"您将看到这样的输出，包括访问MCP检查器的URL：
Starting MCP inspector...
⚙ Proxy server listening on localhost:5080
🔑 Session token:
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
🚀 MCP Inspector is up and running at:
http://localhost:9080/?MCP_PROXY_PORT=5080&MCP_PROXY_AUTH_TOKEN=
🌐 Opening browser...连接到Gemini CLI
要将此MCP服务器与Gemini CLI一起使用，您需要将其添加为源。由于服务器现在使用 stdio，您可以使用以下命令添加它：
gemini mcp add --transport stdio mdspec mdspec添加服务器后，您可以使用 /mcp 使用Gemini CLI中的命令查看可用工具。
工具参考
list_specs(path: str = "", recursive: bool = False, hierarchical: bool = False) -> dict
列出给定目录中的规格。
参数：
path（可选）：相对于的目录路径SPECS_DIR.默认为的根SPECS_DIR.recursive（可选）：如果True，列出所有子目录中的规格。默认为False.hierarchical（可选）：如果True，返回specs目录的树状结构。默认为False.
read_spec(file_path: str) -> dict
读取规范的内容和元数据。
参数：
file_path：规范文件的路径相对于SPECS_DIR.
search_specs(keyword: str, recursive: bool = False, before_context: int = 2, after_context: int = 2) -> dict
在所有规格中搜索关键字。
参数：
keyword：要搜索的关键字。recursive（可选）：如果True，在所有子目录中搜索。默认为False.before_context（可选）：匹配行之前要包含的行数。默认为2。after_context（可选）：匹配行后要包含的行数。默认为2。
search_in_spec(file_path: str, keyword: str, before_context: int = 2, after_context: int = 2) -> dict
在特定规范中搜索关键字。
参数：
file_path：规范文件的路径相对于SPECS_DIR.keyword：要搜索的关键字。before_context（可选）：匹配行之前要包含的行数。默认为2。after_context（可选）：匹配行后要包含的行数。默认为2。
get_table_of_contents(file_path: str) -> dict
从文件中的markdown标题生成目录。
参数：
file_path：规范文件的路径相对于SPECS_DIR.
index_specs() -> dict
索引所有规范以进行语义搜索。
semantic_search(query: str, n_results: int = 5) -> dict
对索引的规格执行语义搜索。
参数：
query：搜索查询。n_results（可选）：要返回的结果数。默认为5。
search_by_tag(tag: str) -> dict
搜索在其正面有特定标签的规格。
参数：
tag：要搜索的标签。
对开发人员的建议提示
以下是一些建议提示，以帮助开发人员有效地使用 mdspec MCP服务器通过Gemini CLI或其他编码代理：
一般信息和发现
- 列出“project_docs”目录中的所有规范，包括它们的最后修改时间
- “显示代码库中所有规范的层次视图。”
- “‘architecture_overview.md’文件中讨论的主要主题是什么？”
- “总结文件‘api_design.md’的内容。”
有针对性的搜索和检索
- “查找所有提及‘身份验证’或‘授权’的规范。”
- “在所有文档中搜索'ChromaDB'的使用情况，并向我展示周围的上下文。”
- “在'troubleshooting.md'文件中，找到所有提到的'错误代码500'，并向我显示它周围的行。”
- “标有‘feature-x’的规格是什么？”
- “哪些规范在语义上与‘如何与外部服务集成’相似？”
代码理解和重构
- “我正在寻找与我们新的支付网关相关的文件。你能找到相关的规格吗？”
- “我需要了解如何管理用户角色。有什么相关文档吗？”
- “找到所有讨论‘性能优化’的规格，并列出它们的标题。”
入职培训和新功能
- “通过列出相关文档，让我对‘用户管理’模块有一个概述。”
- “编写新API端点的最佳实践是什么？向我展示相关规范。”
- “查找有关新‘通知服务’功能的文档。”
有效使用技巧：
- 一致的标记： 鼓励开发人员在他们的规范中使用一致且有意义的标签（例如，在YAML frontmatter中），以最大限度地提高
search_by_tag. - 保持索引最新： 为了使语义搜索提供最相关的结果，请确保
index_specs在规范语料库更改后，该工具会定期运行。