内容
# iwomm-mcp
[](https://github.com/dicoy/iwomm-mcp/actions/workflows/ci.yml)
MCP 服务器，为您的 AI 助手提供对本地开发环境的全面感知 — 运行的进程、Docker 容器、git 状态、开放端口、日志文件等。
停止复制粘贴上下文。让 AI 自行询问所需信息。
---
## 工具列表
| 工具 | 回答内容 |
|---|---|
| `get_running_processes` | 哪些 Node/Python/Go 进程正在运行？端口 3000 上有什么？ |
| `get_docker_state` | 哪些容器正在运行？它们是否健康？它们的端口是什么？ |
| `get_git_status` | 我在哪个分支上？有什么是脏的？我是领先/落后吗？ |
| `get_env_summary` | 我的 `.env` 有哪些键？（值默认掩码） |
| `get_config_summary` | 我的 `application.yml` 中有什么？（`.yml`、`.properties`、`.env`） |
| `get_dependencies` | 我正在使用哪些库？（`pom.xml`、`build.gradle`、`go.mod`、`package.json`） |
| `get_open_ports` | 当前在这台机器上监听的是什么？ |
| `get_recent_logs` | 我的 API 服务在最近 50 行日志中记录了什么？ |
| `get_project_structure` | 这个代码库是什么样子？（gitignore-aware） |
| `check_service_health` | `http://localhost:3000/health` 是否有响应？速度如何？ |
---
## 语言支持
大多数工具在操作系统或网络级别运行，不受堆栈限制。下表列出了工具的适用范围。
| 工具 | Node / TS | Java (Spring) | Go | Python | Ruby / .NET / Rust |
|---|---|---|---|---|---|
| `get_project_structure` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `get_git_status` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `get_docker_state` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `get_open_ports` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `check_service_health` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `get_recent_logs` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `get_running_processes` | ✅ | ⚠️ 所有 JVM 进程都共享名称 `java` — 使用 `filter_name=java` + `filter_args=myapp.jar` | ✅ | ✅ | ✅ |
| `get_env_summary` | ✅ | ⚠️ `.env` 文件仅限 — 使用 `get_config_summary` 获取 `application.*` | ✅ | ✅ | ✅ |
| `get_config_summary` | ✅ | ✅ `.yml` · `.properties` | ❌ | ❌ | ❌ |
| `get_dependencies` | ✅ `package.json` | ✅ `pom.xml` · `build.gradle[.kts]` | ✅ `go.mod` | ❌ | ❌ |
### 仍需复制粘贴的内容
Claude 仍无法读取以下内容 — 需要时请将这些内容粘贴到聊天中：
- **Python 依赖项**：`requirements.txt`、`pyproject.toml`、`setup.py`
- **Rust 依赖项**：`Cargo.toml`
- **Ruby 依赖项**：`Gemfile`
- **.NET 依赖项**：`*.csproj`
- **Python/Rust 配置**：`config.toml`、`settings.py` 及类似格式
- **Java 堆栈跟踪日志**：`get_recent_logs` 返回原始行 — 跨边界的跟踪可能不完整
- **Spring OAuth2 属性**：包含 `auth` 的键（例如 `authorization-grant-type`）被机密检测启发式掩盖；如有需要，请粘贴值
---
## 安装
### 通过 npm（推荐）
```bash
npm install -g iwomm-mcp
```
或在不安装的情况下使用 — `npx` 将按需获取并运行。
### 从源码
```bash
git clone https://github.com/dicoy/iwomm-mcp.git
cd iwomm-mcp
npm install
npm run build
```
### 添加到 Claude Code
```bash
claude mcp add devenv -- npx -y iwomm-mcp
```
### 添加到 Claude Desktop
在 macOS 上添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"devenv": {
"command": "npx",
"args": ["-y", "iwomm-mcp"]
}
}
}
```
重启 Claude。您应该在 `/mcp` 中看到 `devenv`。
---
## 可选：`.mcp-context.yml`
在任何项目的根目录中添加此文件，以告诉 `iwomm-mcp` 关于您的服务：
```yaml
# .mcp-context.yml
services:
api:
port: 3000
logs: ./logs/api.log
health_endpoint: /health
worker:
logs: ./logs/worker.log
postgres:
port: 5432
env_files:
- .env
- .env.local
# 匹配这些模式的键将显示其值
# （即使它们看起来像机密）。支持精确匹配和 * 前缀通配符。
reveal_env_patterns:
- NODE_ENV
- APP_*
- FEATURE_*
```
如果没有此文件，`get_recent_logs` 仅适用于显式文件路径。所有其他工具无需任何配置即可工作。
---
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ Claude（AI） │
└───────────────────────┬─────────────────────────────────┘
│ MCP 协议（stdio）
┌───────────────────────▼─────────────────────────────────┐
│ iwomm-mcp │
│ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ 工具注册表 │ │ 提供者 │ │
│ │ │ │ │ │
│ │ get_git_status ─┼────▶│ IGitProvider │ │
│ │ get_docker_* ─┼────▶│ IDockerProvider │ │
│ │ get_processes ─┼────▶│ IProcessProvider │ │
│ │ ... │ │ IEnvProvider │ │
│ └──────────────────┘ │ ILogProvider │ │
│ │ IPortProvider │ │
│ ┌──────────────────┐ └──────────────┬───────────┘ │
│ │ .mcp-context │ │ │
│ │ .yml │ 具体实现 │
│ └──────────────────┘ │ │
└───────────────────────────────────────────┼─────────────┘
│
┌─────────────┬───────────────┼──────────────┐
▼ ▼ ▼ ▼
ps/lsof simple-git dockerode fs/readline
```
**设计原则：**
- **提供者模式** — 每个工具都依赖于接口，而不是具体实现。测试模拟接口；测试中从不触及操作系统。
- **每个工具一个 Zod 模式** — 相同的模式驱动 MCP 输入验证和 TypeScript 类型。无需重复。
- **类型化的错误层次结构** — `DockerNotAvailableError`、`GitNotARepositoryError` 等。调用者可以捕获他们期望的确切内容。
- **组合根** — `createServer()` 在 `server.ts` 中是唯一一个将接口绑定到实现的地点。其他一切都是纯粹的。
---
## 开发
```bash
npm run dev # 在监视模式下构建
npm run typecheck # tsc --noEmit
npm run lint # biome check
npm run lint:fix # biome check --write
npm run test # vitest run
npm run test:watch # vitest（交互式）
npm run ci # typecheck + lint + test + build
```
### 添加新工具
1. 创建 `src/tools/your-tool-name/schema.ts` — Zod 输入模式
2. 创建 `src/tools/your-tool-name/handler.ts` — 纯函数，注入提供者
3. 创建 `src/tools/your-tool-name/handler.test.ts` — 模拟提供者，而不是操作系统
4. 在 `src/registry/tool-registry.ts` 中注册 — 一个 `server.tool(...)` 调用
如果工具需要新的系统功能，请在 `src/providers/` 中添加接口和对应的实现。处理程序从不导入具体提供者类。
### 项目结构
```
src/
├── config/
│ ├── loader.ts # .mcp-context.yml 解析器
│ └── schema.ts # Zod 模式 + 推断类型
├── errors/
│ └── index.ts # 类型错误层次结构
├── providers/
│ ├── docker.ts # IDockerProvider + DockerodeProvider
│ ├── env.ts # IEnvProvider + FsEnvProvider
│ ├── git.ts # IGitProvider + SimpleGitProvider
│ ├── log.ts # ILogProvider + FsLogProvider
│ ├── port.ts # IPortProvider + LsofPortProvider
│ └── process.ts # IProcessProvider + NodeProcessProvider
├── registry/
│ └── tool-registry.ts # 将工具绑定到 MCP 服务器
├── tools/
│ └── <tool-name>/
│ ├── schema.ts
│ ├── handler.ts
│ └── handler.test.ts
├── index.ts # stdio 传输 + 启动
└── server.ts # createServer() 工厂
```
---
## 技术栈
| | |
|---|---|
| 运行时 | Node.js 20+ |
| MCP SDK | `@modelcontextprotocol/sdk` |
| 验证 | `zod` |
| Git | `simple-git` |
| Docker | `dockerode` |
| Shell | `execa` |
| 构建 | `tsup` |
| 测试 | `vitest` |
| 校验 + 格式化 | `biome` |
