local-stdio-mcp

一个最小可运行、可扩展的本地 stdio MCP 服务。

第一阶段内置 3 个工具：

• ping
• echo
• search_files

其中 search_files 通过 Everything 命令行工具进行文件名搜索，只作为示例模块，不与主服务耦合。

目录结构

local-stdio-mcp/
  README.md
  pyproject.toml
  mcp-settings.json.example
  server.py
  config.py
  modules/
    everything/
      README.md
      backend.py
      tools.py
  shared/
    errors.py
    schemas.py
    utils.py
  tests/
    test_smoke.py

环境准备

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

如果你已经安装了 Everything CLI，可以把 es.exe 放到系统 PATH 中，或者在项目配置文件里指定路径。

配置

在项目根目录创建 mcp-settings.json，内容可参考 mcp-settings.json.example：

{
  "tools": {
    "ping": true,
    "echo": true,
    "search_files": true
  },
  "everything": {
    "enabled": true,
    "path": "",
    "default_limit": 20
  }
}

说明：

• tools.ping 控制是否暴露 ping
• tools.echo 控制是否暴露 echo
• everything.enabled 控制 Everything 模块总开关
• tools.search_files 控制是否暴露 search_files
• everything.path 用于指定 es.exe 路径，支持相对项目根目录的相对路径
• everything.default_limit 控制默认返回条数
• search_files 只有在 everything.enabled=true 且 tools.search_files=true 时才会注册

启动服务

python server.py

该服务使用 stdio 作为 MCP 传输层，适合被支持 MCP 的本地客户端直接拉起。

工具说明

ping

用于检查服务是否存活：

{"ok": true, "message": "pong"}

echo

用于验证参数和返回结构：

输入：

{"text": "hello"}

输出：

{"ok": true, "text": "hello"}

search_files

输入：

{"query": "invoice", "limit": 20}

输出：

{
  "ok": true,
  "backend": "everything",
  "items": [
    {
      "name": "invoice_001.pdf",
      "path": "D:\\Work\\invoice_001.pdf"
    }
  ]
}

错误输出：

{
  "ok": false,
  "error_code": "EVERYTHING_UNAVAILABLE",
  "message": "Everything backend is unavailable"
}

测试

pytest