以下是对该项目的简明使用说明，帮助你快速理解、安装与使用该 MCP 服务器。

• 项目简介

  • 该仓库实现了一个基于 MCP 的服务器，专注于把本地的 Markdown 文档（specs）以统一的接口暴露给 LLM 客户端。服务器提供资源管理（如列出和读取规格文件）、搜索能力（文本搜索与按标签搜索）以及基于向量检索的语义检索能力，并通过 MCP 工具接口对外暴露。

• 主要功能点

  • list_specs(path, recursive, hierarchical): 列出指定路径下的规格文件和目录，支持按层级结构或递归遍历。
  • read_spec(file_path): 读取指定规格文件的内容和 frontmatter 元数据。
  • search_specs(keyword, recursive, before_context, after_context): 在所有规格文件中搜索关键词，并返回匹配行及前后上下文。
  • search_in_spec(file_path, keyword, before_context, after_context): 在单个规格文件中搜索关键词及上下文。
  • get_table_of_contents(file_path): 根据 Markdown 标题生成文件目录信息（Table of Contents）。
  • index_specs(): 将所有规格文本内容索引至向量数据库，供语义检索使用。
  • semantic_search(query, n_results): 基于向量索引执行语义搜索，返回相关结果。
  • search_by_tag(tag): 根据 frontmatter 的 tags 字段筛选并返回匹配的规格文件路径。
  • 配置与安全性：通过 SPECS_DIR 环境变量或默认的 specs 目录定位文档，提供路径安全校验，避免越级访问。

• 安装步骤

  • 准备环境：请确保使用 Python 3.13 及以上版本。
  • 安装依赖并安装本仓库：将代码克隆或下载后，在项目根目录执行安装命令以安装依赖并注册执行脚本（示例为常见做法，实际可能通过 uv/fastmcp 的方式安装与运行）。
  • 设置根目录：通过 SPECS_DIR 环境变量指定规格文件的根目录，若未设置则默认使用仓库中的 specs 目录。
  • 启动服务器：安装完成后，按照项目文档提供的入口命令启动服务器。默认开启标准输入输出（stdio）传输，方便与 MCP 客户端集成。

• 服务器配置（对 MCP 客户端的启动信息描述，示例为文本描述，不以代码块呈现）

  • server_name: "MarkdownSpecs"
  • command: "mdspec"（安装后可执行的主启动命令）
  • args: []（如需额外参数可在此列出，例如某些环境下的 UI 端口或服务器端口等）
  • 备注：该服务器默认通过标准输入输出（stdio）与客户端通信，客户端无需额外的网络端口配置。若要在开发环境启用浏览器调试或可视化 UI，请参照开发模式的指令，使用 Fast MCP 提供的开发命令来启动调试界面。

• 基本使用方法

  • 启动后，客户端通过 MCP 的统一接口向服务器发送请求（如调用 list_specs、read_spec 等工具），服务器返回 JSON-RPC 风格的响应或通知。
  • 在实际工作中，你可以先用 list_specs 浏览文档结构，随后用 read_spec 获取具体文档内容，再用 search_specs/semantic_search 进行内容检索，必要时使用 get_table_of_contents 了解文档结构。
  • 当需要对文档进行语义级检索时，先执行 index_specs 进行向量索引，然后执行 semantic_search 获取相关结果。
  • 如需在本地测试或离线环境，确保 SPECS_DIR 指向存在的 Markdown 文档集合，并可通过 read_spec 等工具读取。

• 额外注意

  • 该实现使用了向量检索（ChromaDB 与 SentenceTransformer），请确保相关依赖在你的运行环境中可用。
  • 通过 read_spec、list_specs 等工具访问的路径都在 SPECS_DIR 指定的根目录内，系统会进行路径安全检查，防止越权访问。