CHIM MCP Server

A Model Context Protocol server that exposes CHIM change-management workflows (changes, outages, retros, and change freeze status) as MCP tools. Register this server with VS Code Copilot, Claude Desktop, or any MCP-compatible agent to query or update CHIM directly from your AI assistant.

🚀 Quick Start

See INSTALL.md for complete installation instructions covering:

• ✅ VS Code + GitHub Copilot
• ✅ Claude Desktop
• ✅ Standalone command line
• ✅ Configuration options

Quick setup (30 seconds):

# 1. Clone and build
git clone https://github.com/abhchoug/chim-mcp.git
cd chim-mcp
npm install && npm run build

# 2. Add full path to your MCP config
# VS Code: ~/Library/Application Support/Code/User/mcp.json
# Claude: ~/Library/Application Support/Claude/claude_desktop_config.json
# (see INSTALL.md for exact configuration)

# 3. Set API key
export CHIM_API_KEY=your-key
# OR create ~/.config/chim-mcp/config.json with {"apiKey": "your-key"}

# 4. Reload VS Code or restart Claude Desktop

# 5. Try: "List my CHIM changes" ✨

Prerequisites

• Node.js 18+ (the server relies on the global fetch implementation)
• A CHIM API key - generate one in the CHIM UI following the API key guide

Configuration

Variable	Default	Description
CHIM_API_KEY	(required)	API key sent as Authorization: Api-Key ….
CHIM_API_BASE_URL	https://api.chim.umbrella.com	Base URL for the CHIM API (set to https://api.stage.chim.umbrella.com for stage).
CHIM_API_USER_AGENT	chim-mcp/0.1.0	Overrides the User-Agent header if you need to identify your automation.

You can also store configuration in ~/.config/chim-mcp/config.json:

{
  "apiKey": "your-key",
  "baseUrl": "https://api.chim.umbrella.com",
  "userAgent": "chim-mcp/0.1.0"
}

Environment variables take precedence over the user-level config file.

Development

git clone https://github.com/cisco-sbg/chim-mcp.git
cd chim-mcp
npm install

# Run in development mode (TypeScript directly)
npm run dev

# Build and run production
npm run build
npm start

Available tools

Tool	Endpoint	Purpose
chim_save_api_key	local	Stores the API key and optional overrides in ~/.config/chim-mcp/config.json.
chim_get_change_freeze_status	GET /api/status/	Returns the global and per-suite change-freeze status documented in api_status.md.
chim_list_changes	GET /api/v1/changes/	Lists change notifications (supports page, page_size, and search query params).
chim_create_change	POST /api/v1/changes/	Creates a change notification. Pass the request body defined in guide.md inside the payload argument.
chim_list_outages	GET /api/v1/outages/	Lists incidents/outages (same pagination parameters as /changes/).
chim_create_outage	POST /api/v1/outages/	Creates an outage notification using the payload described in the guide.
chim_list_retros	GET /api/v1/retros/	Lists retrospective reports for completed incidents/changes.

The create tools accept either:

• payload as a raw JSON string, or
• payload as a structured object (when the calling agent supports complex tool arguments).

Set dry_run: true to have the server validate/echo the payload without sending it to CHIM—handy while drafting.

Testing

Unit Tests

Run the test suite with:

npm test              # Run tests once
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

Manual Testing with JSON-RPC

You can test the server manually by piping JSON-RPC messages:

# List tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npm run dev

# Call a tool (e.g., list changes with search)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chim_list_changes","arguments":{"search":"your-username"}}}' | npm run dev

Extending the interface

1. Review the upstream docs and schema links inside docs/cloudsec/docs/CHIM/api/**. The OpenAPI description is linked in overview.md.
2. Add a helper in src/server.ts that calls the desired CHIM endpoint using the shared ChimClient.
3. Register a new tool with a zod schema to keep inputs validated.
4. Re-run npm run build so the emitted JS in dist/ stays in sync.

The project keeps the MCP implementation small and framework-free, so adding additional CHIM endpoints (pagerduty helpers, key management, etc.) only requires a few lines per tool.

Publishing

To publish a new version:

npm version patch  # or minor/major
npm publish --access public

License

MIT