内容
# meshcore-mcp
[](https://github.com/Greymantle-Risk-Advisory/meshcore-mcp/actions/workflows/ci.yml)
> **采用规格驱动的AI开发方式构建。** 该项目是在高级工程师和安全专业人员的指导和审查下，使用AI辅助、规格优先的开发实践（Claude Code）设计和实现的。架构、安全态势和每次更改都在合并前由人工审查 - 请参阅 [SECURITY.md](SECURITY.md) 获取威胁模型，[docs/architecture.md](docs/architecture.md) 获取设计原理。
一个公开的、只读的 [MCP](https://modelcontextprotocol.io) 服务器，暴露来自 [CoreScope](https://github.com/Kpa-clawbot/CoreScope) MeshCore 分析器实例的实时遥测数据，作为MCP工具。
在Cloudflare Worker上运行。无需身份验证 - 每个包装的端点都是上游分析器上的未经身份验证的公共路由（`GET` 或 `POST`，适用于少数需要JSON正文的端点），因此该服务器不持有任何凭证，也不执行任何写入操作。请参阅 [docs/architecture.md](docs/architecture.md) 获取请求流程，[SECURITY.md](SECURITY.md) 获取威胁模型和已实施的滥用抵抗措施（速率限制、会话TTL、输入验证）。
## 配置
两个值配置了该服务器所讨论的网格 - 两个值都不是提交到存储库的，也不是秘密（一个公共URL和一个显示名称），因此两者都设置为 **GitHub存储库变量** 而不是 `wrangler.jsonc` 字段或Actions秘密：
- `CORESCOPE_BASE_URL` - 此服务器代理的CoreScope实例。没有内置默认值；`wrangler.jsonc` 有一个明显的占位符，因此新的手动部署会大声失败，出现配置错误，而不是静默地命中其他网格的服务器。
- `MESH_NAME` - 用于MCP工具描述中的人类可读名称（例如“_Nebraska Mesh_的网络范围汇总统计”）。纯粹是外观问题 - 如果未设置，不会产生配置错误，只是有一个通用的备用短语。
CI通过 `.github/workflows/ci.yml` 的 `deploy` 作业进行部署，该作业直接使用 `npx wrangler deploy` 进行部署（不是 `cloudflare/wrangler-action` GitHub Action，其 `command:` 输入会进行天真的空格分割，破坏包含空格的 `--var` 值，例如 `MESH_NAME`）。账户ID和API令牌都不是提交的 - 两个值都是存储库秘密，设置一次：
```bash
gh secret set CLOUDFLARE_ACCOUNT_ID --repo Greymantle-Risk-Advisory/meshcore-mcp
gh secret set CLOUDFLARE_API_TOKEN --repo Greymantle-Risk-Advisory/meshcore-mcp
```
## 工具
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `mesh_stats` | 网络范围汇总（节点/观察者/数据包计数） | - |
| `mesh_nodes` | 列表/搜索节点 | `search?`, `role?`, `region?`, `limit?` |
| `mesh_node_detail` | 节点简介 + 健康状况 + 邻居 | `pubkey`（十六进制） |
| `mesh_observers` | 观察者站点列表 | `limit?` |
| `mesh_topology` | 邻居图/拓扑分析 | - |
| `mesh_rf_stats` | 网格上的SNR/RSSI分布 | - |
| `mesh_observations` | 观察记录（谁听到它，SNR/RSSI，路径）最多可容纳200个数据包哈希值 | `hashes`（数组，1-200） |
| `mesh_decode` | 从十六进制表示法解码原始数据包 | `hex` |
| `mesh_path_inspect` | 从截断的跳跃前缀推断最可能的完整节点路径 | `prefixes`（数组，1-64），`observerId?`，`since?`，`until?`，`limit?` |
## 开发
```bash
cp .dev.vars.example .dev.vars # 将本地开发指向实际的CoreScope实例
npm install
npm test # vitest
npm run type-check
npm run dev # wrangler dev，在 http://localhost:8787/mcp 提供服务
```
`.dev.vars` 被 gitignore 并且仅由 `wrangler dev` 使用 - 它永远不会被发布。
## 部署
**自动：** 每次推送到 `main` 分支并通过CI后，会通过 `.github/workflows/ci.yml` 的 `deploy` 作业进行部署（直接使用 `npx wrangler deploy` - 不是 `cloudflare/wrangler-action` GitHub Action，其 `command:` 输入会进行天真的空格分割，破坏包含空格的 `--var` 值，例如 `MESH_NAME`）。账户ID和API令牌都不是提交的 - 两个值都是存储库秘密，设置一次：
```bash
gh secret set CLOUDFLARE_ACCOUNT_ID --repo Greymantle-Risk-Advisory/meshcore-mcp
gh secret set CLOUDFLARE_API_TOKEN --repo Greymantle-Risk-Advisory/meshcore-mcp
```
**手动：** `wrangler` 还需要账户ID作为本地命令的真实环境变量（`wrangler.jsonc` 故意没有 `account_id` 字段），并且需要配置 `CORESCOPE_BASE_URL`/`MESH_NAME` 占位符，除非您还传递 `--var`:
```bash
CLOUDFLARE_ACCOUNT_ID=<您的账户ID> npm run deploy
# 或，要覆盖占位符：
CLOUDFLARE_ACCOUNT_ID=<您的账户ID> npx wrangler deploy \
--var 'CORESCOPE_BASE_URL:https://your-corescope-instance.example.com' \
--var 'MESH_NAME:您的网格名称'
```
## 连接客户端
Cloudflare AI Playground： https://playground.ai.cloudflare.com/，输入部署的 `/mcp` URL。
Claude Desktop（通过 [mcp-remote](https://www.npmjs.com/package/mcp-remote)）：
```json
{
"mcpServers": {
"meshcore": {
"command": "npx",
"args": ["mcp-remote", "https://<您的工作器>.workers.dev/mcp"]
}
}
}
```
## 许可证
[GPL-3.0-or-later](LICENSE)。该项目以 **不支持且不提供任何形式的保修** 的方式发布 - 有关完整的免责声明，请参阅许可证。话虽如此，欢迎提交拉取请求；请参阅 [AGENTS.md](AGENTS.md) 获取此代码库期望的约定。
