# local-stdio-mcp

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

第一阶段内置 3 个工具：

- `ping`
- `echo`
- `search_files`

其中 `search_files` 通过 `Everything` 命令行工具进行文件名搜索，只作为示例模块，不与主服务耦合。该工具只会在 Windows 平台注册。

## 目录结构

```text
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
```

## 环境准备

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

如果你已经安装了 Everything CLI，可以把 `es.exe` 放到系统 `PATH` 中，或者在项目配置文件里指定路径。非 Windows 平台不会暴露 `search_files`。

## 配置

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

```json
{
  "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` 只有在 Windows 平台且 `everything.enabled=true` 且 `tools.search_files=true` 时才会注册

## 启动服务

```powershell
python server.py
```

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

## 工具说明

### `ping`

用于检查服务是否存活：

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

### `echo`

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

输入：

```json
{"text": "hello"}
```

输出：

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

### `search_files`

输入：

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

输出：

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

错误输出：

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

## 测试

```powershell
pytest
```