ops-mcp

ops-mcp Remote MCP Ops platform for AI Agents. Claude Code, Codex, ChatGPT Agent, etc. can be connected to ops-mcp via **HTTP Remote MCP API** to call Linux operation and maintenance, SSH remote execution, Docker / database / Redis / Kafka query, HTTP API based on OpenAPI, command connector to call local whitelist CLI (e.g., `ping`), SNMP connector to query switches, and TCP/UDP connector to connect private byte protocol devices. ## Core Concept **Capability is a visible Tool.** - No capability exists without a disk plugin or an OpenAPI operation exposed through Discovery. - Disk capabilities correspond to independent plugins (e.g., `linux_ls`, `docker_ps`, `redis_ping`); HTTP API can be automatically generated into Tools by `apis.yaml` + OpenAPI. - Disk plugins consist of `plugin.yml` + `main.js`; Go is responsible for protocol, loading, verification, and connectors, while JavaScript (Goja) is responsible for orchestration and invocation. OpenAPI Tools do not go through Goja. ## Current Status **Phase 0–9 completed** (including Phase 9 TCP/UDP). See [docs/roadmap.md](docs/roadmap.md) for details. | Included | Not Implemented | |----------|-----------------| | MCP Remote Server (`POST /mcp`) | RBAC / User System | | Plugin Framework + Goja | Permission / Audit | | SSH Connector (`hosts.yaml`) | allow_rules / deny_rules | | Docker Connector (via SSH) | — | | MySQL / PostgreSQL / Redis / Kafka Connector + Plugin | — | | Linux + Docker + DB + Redis + Kafka Basic Plugin | — | | HTTP API: `apis.yaml` + OpenAPI → MCP Tool (Phase 6) | ops-mcp's own Swagger UI | | Command Connector: `commands.yaml` whitelist + local CLI Plugin (Phase 7) | — | | SNMP Connector: `snmp.yaml` + get/walk/bulk / sysinfo / interfaces (Phase 8) | — | | TCP / UDP Connector: `ctx.tcp` / `ctx.udp` + smoke Plugin (Phase 9) | — | ## Quick Start ```bash # 1. Copy and fill in real credentials (do not submit) cp config/hosts.yaml.example config/hosts.yaml cp config/databases.yaml.example config/databases.yaml cp config/redis.yaml.example config/redis.yaml cp config/kafka.yaml.example config/kafka.yaml # Optional; Kafka read-only query cp config/apis.yaml.example config/apis.yaml # Optional; OpenAPI → MCP Tool # config/commands.yaml already includes common local CLI whitelist (ping/dig/…); modify path array by environment cp config/snmp.yaml.example config/snmp.yaml # Optional; switch SNMP make snmp-up # Optional; local SNMP simulator UDP 1161 (deploy/dev-snmp) make net-up # Optional; local TCP/UDP echo 19090/19091 (deploy/dev-net) # 2. Compile and test make check # 3. Start (development) make run ``` ### Production Installation (systemd) ```bash make tar GOOS=linux GOARCH=amd64 # Copy dist/ops-mcp-*.tar.gz to the server and then: tar -xzf ops-mcp-*-linux-amd64.tar.gz cd ops-mcp-*-linux-amd64 sudo ./deploy/install.sh ``` See [docs/user-guide.md](docs/user-guide.md) and [deploy/README.md](deploy/README.md) for details. Default listening address is in `config/ops-mcp.yaml` (localhost development commonly uses `20267`). Open `http://localhost:20267/` in a browser to view current Tools and resource configuration (static page public; enter a token that matches `server.auth.token` to load `/api/*`). ### Smoke Test ```bash TOKEN=ops-mcp-local-dev-token # Matches config/ops-mcp.yaml server.auth.token curl -s localhost:20267/health | jq . curl -s -H "Authorization: Bearer $TOKEN" localhost:20267/api/plugins | jq . curl -s -X POST localhost:20267/mcp \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` ### Claude Code Integration Create `.mcp.json` in any project directory (must include token): ```json { "mcpServers": { "ops-mcp": { "type": "http", "url": "http://127.0.0.1:20267/mcp", "headers": { "Authorization": "Bearer ops-mcp-local-dev-token" } } } } ``` Alternatively, use environment variables: `Authorization: Bearer ${OPS_MCP_AUTH_TOKEN}`, and align with server-side `OPS_MCP_AUTH_TOKEN` / `server.auth.token`. Call examples: - `list_hosts`: no parameters - `docker_ps`: `host=dev-ssh-111` / `dev-ssh-112` - `linux_top`: `host=dev-ssh-111`, `count=10` - `redis_ping`: `redis=local-redis` ## Directory Structure ``` ops-mcp/ ├── cmd/server/ ├── internal/ │ ├── api/ │ mcp/ │ ├── plugin/ │ ├── runtime/ │ ├── executor/ │ ├── connector/{ssh,docker,mysql,postgres,redis,http,dbutil,sqlguard}/ ├── openapi/ #6: OpenAPI / Discovery / Tool generation │ ├── config/ │ └── model/ ├── plugins/{linux,docker,mysql,postgres,redis,hosts,databases,apis}/ ├── config/ ├── deploy/ └── docs/ ``` ## Documentation | Document | Description | |----------|-------------| | [docs/user-guide.md](docs/user-guide.md) | **User Manual** (introduction / deployment / built-in Plugin / custom Plugin) | | [cursor.md](cursor.md) | Agent development context and test completion gate | | [docs/architecture.md](docs/architecture.md) | Architecture | | [docs/api.md](docs/api.md) | HTTP / MCP API | | [docs/plugin.md](docs/plugin.md) | Plugin framework | | [docs/runtime.md](docs/runtime.md) | Goja ctx API | | [docs/connector.md](docs/connector.md) | Connector | | [docs/configuration.md](docs/configuration.md) | Configuration | | [docs/apis.md](docs/apis.md) | HTTP `