Chatwoot MCP

Local Node/TypeScript MCP split for read-only Chatwoot analytics.

This service is intended to replace the MCP surface of the current Python combined server after shadow testing. It does not process Chatwoot webhooks and does not generate embeddings.

Current Scope

This repo has Node/TypeScript registrations for all 66 Python MCP tools from the previous combined server, plus Node-first read-only tools for clearer agent workflows.

For recent conversation audit requests like "last 7 days all conversations summary per inbox", agents should use get_recent_resolved_conversation_summaries_by_inbox. It returns cached resolved conversations grouped by account/inbox with each Chatwoot conversation ID and a compact transcript summary. If the user names an account, brand, inbox, product, or channel, call list_available_chatwoot_scope first and pass selected account_id and/or inbox_ids.

Semantic/vector tools remain embedding-free in this repo. They call the split Python embedding service through:

EMBEDDING_SERVICE_URL=http://127.0.0.1:8000
EMBEDDING_API_KEY=YOUR_EMBEDDING_SERVICE_X_API_KEY

Tool parity notes are tracked in docs/PORTING_CHECKLIST.md.

Transports

Default mode is stdio:

npm run build
npm start

HTTP mode:

npm run build
npm run start:http

Legacy SSE compatibility mode uses the same HTTP server:

npm run start:sse

Routes are mounted under BASE_PATH:

• GET ${BASE_PATH}/health
• POST/GET ${BASE_PATH}/mcp for Streamable HTTP
• GET ${BASE_PATH}/sse for legacy SSE
• POST ${BASE_PATH}/messages for legacy SSE client messages

If MCP_API_KEY is set, Authorization: Bearer <key> is required.

Local Setup

npm install
cp .env.example .env
npm run build
npm run start:http

Windows PowerShell:

npm install
Copy-Item .env.example .env
npm run build
npm run start:http

Shadow Testing

Run locally with a non-production port/path:

PORT=3010
BASE_PATH=/node-mcp

Then compare selected tools against the live Python MCP before exposing this behind Nginx.

Nginx Notes

Use path-preserving proxying. Do not depend on rewrite-only behavior because SSE advertises the POST message URL back to clients.

location /node-mcp/ {
    proxy_pass http://127.0.0.1:3010/node-mcp/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Authorization $http_authorization;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

Production Safety

Keep the live Python MCP endpoint unchanged until:

1. Every required tool has Node parity.
2. Date/timezone output matches expected semantics.
3. ChatGPT/Codex/Claude clients can connect to the shadow path.
4. A rollback path is documented.