mango-cms-mcp

Production-ready Model Context Protocol server for the Mango CMS framework.

It gives LLMs (Claude, Cursor, Windsurf, VS Code Copilot, etc.) accurate, version-aware access to:

• Framework documentation and source
• (When using the local version) your project's actual collection schemas, permissions, hooks, fields
• Canonical explanations of tricky internals (so LLMs stop guessing):
  • How collection authentication is processed on every request
  • Exactly how relationships are stored in the raw MongoDB documents (always arrays of IDs)
  • Request lifecycle, translateInput/Output timing, depth handling
  • How to correctly fetch/list/create via the REST endpoints (and GraphQL differences)
  • Field types, custom fields, globalFields, etc.

Full per-project collection awareness is provided by the local stdio mode (see Usage below). A centralized hosted service is planned as a future implementation.

Installation

For LLM agents to use the local (project-aware) MCP instance via npx:

Install this package as a dev dependency inside your Mango CMS project (the one containing your mango/ or config/ folder and package.json that depends on mango-cms):

npm install --save-dev mango-cms-mcp
# or
yarn add -D mango-cms-mcp

This ensures that when an agent config uses npx mango-cms-mcp, it will resolve to the local copy in your project's node_modules. The server will then run with your project's directory as the current working directory, enabling automatic discovery of your exact mango-cms version and your real collection schemas/endpoints.

(For developing this MCP package itself, see the Development section below.)

Usage with AI Tools

Local (Recommended) — Use npx from your project

This is the way to make LLM agents (Cursor, Claude Desktop, Windsurf, VS Code, etc.) spawn the local MCP instance using npx.

After installing as a dev dependency in your Mango project (see Installation above), configure your agent to use:

{
  "mcpServers": {
    "mango-cms": {
      "command": "npx",
      "args": ["mango-cms-mcp"]
    }
  }
}

• npx mango-cms-mcp will automatically find and run the version installed in your project's node_modules/.bin/.
• The process starts with your project's root as cwd, so it auto-detects the correct mango-cms version from your package.json and parses your actual collections, permissions, hooks, and endpoints from disk (using a safe AST parser, no side effects or execution of your code).
• This gives the LLM accurate, project-specific knowledge + the canonical framework internals.

The AI coding tool handles spawning the server (via stdio) and exposing its tools/resources/prompts to the LLM. No global install or manual process management is needed.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mango-cms": {
      "command": "npx",
      "args": ["mango-cms-mcp"]
    }
  }
}

(For development of this package, see below. The npx form above is what you want agents to use in normal projects.)

Cursor / Other stdio MCP clients

Cursor (and similar tools) lets you configure MCP servers either globally or per-project.

Recommended for normal use: install as devDep (see Installation) and use the simple npx config in your agent settings (global or project). This makes agents use npx mango-cms-mcp which resolves to your local installed instance.

For direct development/testing of changes in this repo (before publishing):

Use a project-scoped config in a real Mango project:

1. Open a Mango CMS project in Cursor (one that has mango-cms in its dependencies and a mango/ or config/ folder).

2. In the project root, create .cursor/mcp.json (create the .cursor folder if needed) with:

{
  "mcpServers": {
    "mango-cms": {
      "type": "stdio",
      "command": "npx",
      "args": ["mango-cms-mcp"]
    }
  }
}

• When the project is open, Cursor will use this config.
• The server process is spawned with the project directory as its working directory, so auto-detection of your exact mango-cms version and your real collections works perfectly.

For development/testing your latest local changes (e.g. after git push and pulling the clone):

Use an absolute path to your local build instead of npx:

{
  "mcpServers": {
    "mango-cms": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/your/mango-cms-mcp/dist/index.js"]
    }
  }
}

(Replace the path with your clone location, e.g. /Users/you/sites/mango-cms-mcp/dist/index.js.)

Alternative (cleaner for dev):

In your mango-cms-mcp clone directory, run:

npm run build
npm link

Then use this simpler config (the mango-cms-mcp command will point to your local version):

{
  "mcpServers": {
    "mango-cms": {
      "type": "stdio",
      "command": "mango-cms-mcp"
    }
  }
}

After code changes: npm run build (re-link only if the bin mapping changes).

Via Cursor UI (easiest for global config):

• Open Cursor Settings (Cmd/Ctrl + ,)
• Go to Tools & MCP (or search "MCP")
• Click + Add New MCP Server (or "Add new global MCP server")
• This opens ~/.cursor/mcp.json (global) — paste the JSON object above.
• Project-level files (.cursor/mcp.json) take precedence when the project is open.

After saving, the server should appear in the MCP list (you may need to restart Cursor or start a fresh Agent/Composer session). Look for "mango-cms" under available tools.

Tip: For the most accurate behavior, always test while a real Mango CMS project is the active workspace/folder in Cursor. The server relies on the current working directory for discovery.

It auto-detects the mango-cms version from your project's package.json and the location of your mango/ or config/ directory. This full per-project discovery only works in local stdio mode.

Hosted / Remote (Future Implementation)

We plan to offer an official hosted instance at https://mcp.mangojs.com/mcp.

This will allow developers to add the server once in their global/user-level MCP client settings (e.g. Cursor settings or Claude config) with no local npm install, no per-project configuration, and no need to run anything on their machine.

Example configuration (will be documented in full when the service launches):

{
  "mcpServers": {
    "mango-cms": {
      "url": "https://mcp.mangojs.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Note on hosted behavior: The hosted version will provide excellent framework-level knowledge (internals explanations, field types, documentation, and source access for a canonical mango-cms version). However, it will run on the server and therefore cannot automatically discover your local project's collections, permissions, or code. Project-specific tools (list_project_collections, get_collection_schema, etc.) will reflect server-side reference data (or be limited). For full awareness of your actual project, use the local stdio version above.

The official hosted service at mcp.mangojs.com is a future implementation. The underlying code to run the server over HTTP transport exists today (see below for self-hosting/testing), but the public hosted deployment and service details are not yet live.

HTTP Transport (Streamable HTTP) — Self-Hosting & Testing

The server supports the Streamable HTTP transport in addition to the default stdio. This is useful for:

• Local testing of HTTP mode
• Self-hosting (e.g. with PM2 on your own infrastructure)
• Will power the future official hosted service at mcp.mangojs.com

The default is still stdio for desktop clients. To run over HTTP:

# via CLI flags (CLI wins)
npx mango-cms-mcp --transport http --port 3000 --host 127.0.0.1 --api-key mysecret

# via env (or mix)
TRANSPORT=http PORT=3000 MANGO_MCP_API_KEY=mysecret npx mango-cms-mcp

• Mounts at POST/GET/DELETE http://127.0.0.1:3000/mcp
• Stateful sessions with mcp-session-id header (per MCP spec).
• Security: If --api-key (or MANGO_MCP_API_KEY / MCP_API_KEY) is set, requires X-API-Key: <key> or Authorization: Bearer <key>. Uses timing-safe compare. Without key on non-localhost: warning logged.
• CORS: Enabled; CORS_ORIGIN env sets origin (defaults *); exposes mcp-session-id.
• Localhost binds use SDK host header validation (DNS rebinding protection).
• Graceful shutdown on SIGINT/SIGTERM.

PM2 usage (for self-hosting the HTTP server persistently):

pm2 start ./node_modules/.bin/mango-cms-mcp --name mango-mcp -- --transport http --port 3000 --api-key "$MANGO_MCP_API_KEY"
# or with ecosystem.config.js:
# module.exports = { apps: [{ name: 'mango-mcp', script: 'mango-cms-mcp', args: '--transport http --port 3000 --api-key secret' }] }

MCP clients that support remote Streamable HTTP MCP servers can connect to a self-hosted instance at your chosen URL (supply the API key via Authorization: Bearer ... or X-API-Key: ... header). The official public endpoint at https://mcp.mangojs.com/mcp will be announced when the hosted service launches.

See package.json scripts: npm run start:http.

What it provides

Resources (browseable):

• mango://version
• mango://framework/readme
• mango://internals/auth
• mango://internals/relationships
• mango://internals/lifecycle
• mango://internals/data-fetch
• mango://project/collections
• mango://project/collection/{name}
• mango://project/endpoints
• mango://framework/source/{relativePath} (live from installed mango-cms/src when present)
• mango://context/search/{query}

Tools:

• get_mango_version
• list_project_collections
• get_collection_schema
• search_mango_knowledge
• explain_mango_concept
• get_field_types
• get_mango_source_file
• list_project_endpoints
• get_relationship_db_shape
• get_auth_processing_details

Prompts:

• mango_cms_expert
• implement_mango_collection
• debug_mango_api_call

Icon / Branding in Chat

The server declares an official icon (a friendly mango + code motif) via the MCP icons field in its serverInfo (per the 2025 MCP spec).

• A data: URI embedded version is always provided (works everywhere).
• A file:/// URI is also provided for local stdio clients (VS Code explicitly supports this for desktop stdio servers).

This makes the Mango CMS MCP appear with its logo in Cursor, VS Code chat/agent UI, and other clients that render server icons. No extra configuration needed.

Regenerating Context for a New mango-cms Version

When a new version of mango-cms is published:

# 1. Checkout the exact mango-cms version (or let CI do it)
git clone --depth 1 --branch v0.3.22 https://.../mango-cms /tmp/mango-cms-v0.3.22

# 2. Regenerate
cd mango-cms-mcp
npm run generate:context -- --mango /tmp/mango-cms-v0.3.22 --version 0.3.22

# 3. Commit the new context/v0.3.22/ + latest/ updates + bump package version
git add context/ package.json
git commit -m "chore: context for mango-cms 0.3.22"
npm version patch
npm publish

CI Automation

See .github/workflows/regenerate-context.yml. It supports workflow_dispatch with a mango_version input. The job checks out the specified tag of mango-cms, runs the generator, and can open a PR or push a branch with the updated context.

You can trigger it from the mango-cms release workflow via repository_dispatch or manually after publishing a new mango-cms version.

Development

npm install
npm run build
npm run dev          # runs the stdio server (connect an MCP client to it) — recommended for local use
npm run dev -- --transport http --port 34567 --api-key test  # http mode (for testing the transport / self-hosting)
npm run start:http   # after build (http for self-hosting or future hosted use)
npm run generate:context -- --mango ../mango-cms
npm test

The server is intentionally lightweight and has no external service dependencies.

Publishing to npm (for new releases)

This package is intended to be consumed via npx (or as a devDependency) so LLM agents can easily spawn the local project-aware instance.

Typical release steps (run from a clean clone of main):

# 1. Make sure everything is built and tests pass
npm test
npm run build

# 2. Update version (patch / minor / major). This also creates a git tag.
npm version patch -m "chore: release %s (npx-friendly local MCP for agents)"

# 3. (Optional but recommended) Dry-run to preview the tarball contents
npm publish --dry-run

# 4. Publish (requires being logged in with `npm login`, and having publish rights for the name)
npm publish

# 5. Push the commit + tag
git push && git push --tags

After publishing, consumers can do:

npm install --save-dev mango-cms-mcp
# then configure agents with "command": "npx", "args": ["mango-cms-mcp"]

Test immediately with npx mango-cms-mcp@latest --help from a temp dir (or a real project for full discovery).

See also the "Regenerating Context" section — context updates are usually done as part of releases.

License

Commercial (same as mango-cms).