iwomm-mcp

An MCP server that gives your AI assistant full awareness of your local dev environment — running processes, Docker containers, git state, open ports, log files, and more.

Stop copy-pasting context. Let the AI ask for what it needs.

---

Tools

Tool	What it answers
get_running_processes	What Node/Python/Go processes are running? What's on port 3000?
get_docker_state	Which containers are up? Are they healthy? What are their ports?
get_git_status	What branch am I on? What's dirty? Am I ahead/behind?
get_env_summary	What keys does my .env have? (Values masked by default)
get_config_summary	What's in my application.yml? (.yml, .properties, .env)
get_dependencies	What libraries am I using? (pom.xml, build.gradle, go.mod, package.json)
get_open_ports	What's listening on this machine right now?
get_recent_logs	What did my API service log in the last 50 lines?
get_project_structure	What does this codebase look like? (gitignore-aware)
check_service_health	Is http://localhost:3000/health responding? How fast?

---

Language support

Most tools operate at the OS or network level and work regardless of stack. The table below calls out the gaps.

Tool	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	✅	⚠️ all JVM processes share the name java — use filter_name=java + filter_args=myapp.jar	✅	✅	✅
get_env_summary	✅	⚠️ .env files only — use get_config_summary for application.*	✅	✅	✅
get_config_summary	✅	✅ .yml · .properties	❌	❌	❌
get_dependencies	✅ package.json	✅ pom.xml · build.gradle[.kts]	✅ go.mod	❌	❌

What still needs copy-paste

Some things Claude can't read yet — paste these into chat when needed:

• Python deps: requirements.txt, pyproject.toml, setup.py
• Rust deps: Cargo.toml
• Ruby deps: Gemfile
• .NET deps: *.csproj
• Python/Rust config: config.toml, settings.py and similar formats
• Java stack traces in logs: get_recent_logs returns raw lines — a trace split across the tail boundary may arrive incomplete
• Spring OAuth2 properties: keys containing auth (e.g. authorization-grant-type) are masked by the secret-detection heuristic; paste the value if needed

---

Installation

Via npm (recommended)

npm install -g iwomm-mcp

Or use it without installing — npx will fetch and run it on demand (see Claude config below).

From source

git clone https://github.com/dicoy/iwomm-mcp.git
cd iwomm-mcp
npm install
npm run build

Add to Claude Code

claude mcp add devenv -- npx -y iwomm-mcp

Add to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "devenv": {
      "command": "npx",
      "args": ["-y", "iwomm-mcp"]
    }
  }
}

Restart Claude. You should see devenv in /mcp.

---

Optional: .mcp-context.yml

Drop this file at the root of any project to tell iwomm-mcp about your services:

# .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

# Keys matching these patterns will have their values revealed
# (even if they look like secrets). Supports exact match and * prefix glob.
reveal_env_patterns:
  - NODE_ENV
  - APP_*
  - FEATURE_*

Without this file, get_recent_logs works only with explicit file paths. All other tools work without any config.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Claude (AI)                          │
└───────────────────────┬─────────────────────────────────┘
                        │ MCP protocol (stdio)
┌───────────────────────▼─────────────────────────────────┐
│                    iwomm-mcp                             │
│                                                          │
│  ┌──────────────────┐     ┌──────────────────────────┐  │
│  │   Tool Registry  │     │       Providers          │  │
│  │                  │     │                          │  │
│  │  get_git_status ─┼────▶│  IGitProvider            │  │
│  │  get_docker_*   ─┼────▶│  IDockerProvider         │  │
│  │  get_processes  ─┼────▶│  IProcessProvider        │  │
│  │  ...             │     │  IEnvProvider            │  │
│  └──────────────────┘     │  ILogProvider            │  │
│                            │  IPortProvider           │  │
│  ┌──────────────────┐     └──────────────┬───────────┘  │
│  │  .mcp-context    │                     │              │
│  │     .yml         │           concrete impls           │
│  └──────────────────┘                     │              │
└───────────────────────────────────────────┼─────────────┘
                                            │
              ┌─────────────┬───────────────┼──────────────┐
              ▼             ▼               ▼              ▼
           ps/lsof      simple-git      dockerode       fs/readline

Design principles:

• Provider pattern — every tool depends on an interface, not a concrete implementation. Tests mock the interface; the OS is never touched in tests.
• One Zod schema per tool — the same schema drives both MCP input validation and TypeScript types. No duplication.
• Typed error hierarchy — DockerNotAvailableError, GitNotARepositoryError, etc. Callers can catch exactly what they expect.
• Composition root — createServer() in server.ts is the only place that wires interfaces to implementations. Everything else is pure.

---

Development

npm run dev          # build in watch mode
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 (interactive)
npm run ci           # typecheck + lint + test + build

Adding a new tool

1. Create src/tools/your-tool-name/schema.ts — Zod input schema
2. Create src/tools/your-tool-name/handler.ts — pure function, injected providers
3. Create src/tools/your-tool-name/handler.test.ts — mock the providers, not the OS
4. Register in src/registry/tool-registry.ts — one server.tool(...) call

If the tool needs a new system capability, add an interface to src/providers/ with a corresponding implementation. The handler never imports a concrete provider class.

Project structure

src/
├── config/
│   ├── loader.ts          # .mcp-context.yml parser
│   └── schema.ts          # Zod schema + inferred types
├── errors/
│   └── index.ts           # typed error hierarchy
├── 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   # wires tools to the MCP server
├── tools/
│   └── <tool-name>/
│       ├── schema.ts
│       ├── handler.ts
│       └── handler.test.ts
├── index.ts               # stdio transport + startup
└── server.ts              # createServer() factory

---

Tech stack

Runtime	Node.js 20+
MCP SDK	@modelcontextprotocol/sdk
Validation	zod
Git	simple-git
Docker	dockerode
Shell	execa
Build	tsup
Tests	vitest
Lint + format	biome