From 98684af0475414b26d3ed2eb02f2db98b10b17a9 Mon Sep 17 00:00:00 2001 From: AHMET BAYHAN BAYRAMOGLU <49499275+ABB65@users.noreply.github.com> Date: Sun, 12 Jul 2026 14:17:37 +0300 Subject: [PATCH] docs(mcp): registry manifest upgrade + multi-client distribution docs Prepare @contentrain/mcp for MCP directory submission: - server.json: add title, websiteUrl, repository.subfolder, registryBaseUrl, sync version to 1.8.1 (CI keeps it in sync on release), and advertise the Studio MCP Cloud remote (streamable-http endpoint + Bearer key header) - package.json: correct tool count in description (17 -> 19), add claude-code/codex keywords - docs: new MCP Distribution Surfaces table (ecosystem), OpenAI Codex + Claude Desktop + Claude Code connection guides with MCP Cloud variants (getting-started, packages/mcp), Studio MCP Cloud deployment pattern (guides/http-transport), Discovery section (packages/mcp) - rules/skills READMEs + docs/packages/rules.md: MCP_TOOLS count 17 -> 19 (matches packages/rules/src/index.ts) --- docs/ecosystem.md | 10 +++++ docs/getting-started.md | 25 ++++++++++- docs/guides/http-transport.md | 16 +++++++ docs/packages/mcp.md | 79 ++++++++++++++++++++++++++++++++++- docs/packages/rules.md | 2 +- packages/mcp/package.json | 4 +- packages/mcp/server.json | 32 ++++++++++++-- packages/rules/README.md | 4 +- packages/skills/README.md | 2 +- 9 files changed, 163 insertions(+), 11 deletions(-) diff --git a/docs/ecosystem.md b/docs/ecosystem.md index eb80b41..3c794ad 100644 --- a/docs/ecosystem.md +++ b/docs/ecosystem.md @@ -42,6 +42,16 @@ Use **Contentrain Studio** when you need: | `@contentrain/rules` | Quality standard and schema/content guardrails | Studio should match the same quality standard in chat, review, and content validation | [Rules & Skills](/packages/rules), [Studio Architecture](https://docs.contentrain.io/developer/architecture) | | `@contentrain/skills` | Agent playbooks, workflow hints, and normalize/review procedures | Studio mirrors these workflows in chat-led operations, onboarding, and promotion moments | [Rules & Skills](/packages/rules), [Studio AI Chat](https://docs.contentrain.io/guide/ai-chat) | +## MCP Distribution Surfaces + +| Surface | What users see | Best fit | +|---|---|---| +| MCP Registry | `io.github.Contentrain/contentrain` | Discover and install the local `@contentrain/mcp` server from MCP-compatible clients | +| OpenAI Codex | `codex mcp add`, `.codex/config.toml`, and future plugin packaging | Developers who want Contentrain tools inside Codex CLI, desktop, or IDE workflows | +| Claude Desktop | `claude_desktop_config.json` | Local desktop users who want a checkout-scoped Contentrain server | +| Claude Code | `claude mcp add`, `.mcp.json`, and plugin marketplaces | Coding-agent workflows with project-scoped MCP approval and skills | +| Studio MCP Cloud | Hosted Streamable HTTP endpoint + API key | Teams that want external agents to operate a Studio project without sharing a local checkout | + ## Product Philosophy - **Governance, not generation** — Contentrain standardizes, validates, and reviews content. Your model provider still does the generation. diff --git a/docs/getting-started.md b/docs/getting-started.md index 745a1ab..7f893c7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -14,7 +14,7 @@ Contentrain AI is an open-source, repo-native content governance stack. Your AI - Node.js 22+ - Git -- An MCP-compatible AI agent (Claude Code, Cursor, Windsurf, or similar) +- An MCP-compatible AI agent (OpenAI Codex, Claude Desktop, Claude Code, Cursor, Windsurf, or similar) ## Choose Your Path @@ -78,6 +78,23 @@ npx contentrain setup windsurf # → creates .windsurf/mcp.json npx contentrain setup --all # → configures all detected IDEs ``` +OpenAI Codex and Claude Desktop can be connected manually: + +```bash +codex mcp add contentrain -- npx -y contentrain serve --stdio +``` + +```json +{ + "mcpServers": { + "contentrain": { + "command": "npx", + "args": ["-y", "contentrain", "serve", "--stdio"] + } + } +} +``` + ::: tip Auto-configured during init If your IDE is detected during `contentrain init`, the MCP config is created automatically — you may already be set up. ::: @@ -98,6 +115,8 @@ If your IDE is detected during `contentrain init`, the MCP config is created aut | IDE | Config file | |-----|-------------| +| OpenAI Codex | `.codex/config.toml` or `~/.codex/config.toml` | +| Claude Desktop | `claude_desktop_config.json` | | Claude Code | `.mcp.json` (project root) | | Cursor | `.cursor/mcp.json` | | VS Code | `.vscode/mcp.json` | @@ -115,6 +134,10 @@ npx contentrain serve --mcpHttp --authToken $(openssl rand -hex 32) See the [HTTP Transport guide](/guides/http-transport) for auth, deployment patterns, and programmatic embedding. ::: +::: tip Studio MCP Cloud +When the project is connected to Studio, Workspace Settings → MCP Cloud creates a hosted Streamable HTTP endpoint and project-scoped API key. Use that endpoint for Codex, Claude Desktop, Claude Code, Cursor, or any MCP client that should operate the Studio project without a local checkout. +::: + ### 3. Create a content model Tell your agent: diff --git a/docs/guides/http-transport.md b/docs/guides/http-transport.md index 5bb857e..14c94b3 100644 --- a/docs/guides/http-transport.md +++ b/docs/guides/http-transport.md @@ -75,6 +75,22 @@ The same pattern works for `createGitLabProvider` with a `GitLabProvider`. Both ## Deployment patterns +### Studio MCP Cloud + +Studio MCP Cloud is the hosted version of the HTTP transport for connected Studio projects. It exposes: + +```text +https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp +``` + +Authentication uses a project-scoped MCP Cloud API key: + +```http +Authorization: Bearer +``` + +Studio handles the gates around that endpoint: project matching, plan access, per-key rate limits, optional tool allowlists, monthly call quotas, usage metering, and branch reconciliation. External clients such as OpenAI Codex, Claude Desktop, Claude Code, Cursor, and custom MCP drivers connect to the same Streamable HTTP shape as a self-hosted `contentrain serve --mcpHttp` server. + ### Studio (hosted agent) Studio's agent builds a GitHubProvider or GitLabProvider per tenant, points it at the tenant's content repo, and talks to an embedded MCP server over HTTP+LocalProvider-style wiring but with a remote provider. Each session is ephemeral. diff --git a/docs/packages/mcp.md b/docs/packages/mcp.md index 16fb14a..0a2ed59 100644 --- a/docs/packages/mcp.md +++ b/docs/packages/mcp.md @@ -1,6 +1,6 @@ --- title: MCP Tools -description: Complete reference for @contentrain/mcp — the provider-agnostic MCP engine powering AI content governance with 17 deterministic tools over stdio or HTTP +description: Complete reference for @contentrain/mcp — the provider-agnostic MCP engine powering AI content governance with 19 deterministic tools over stdio or HTTP order: 1 slug: mcp --- @@ -41,6 +41,18 @@ Optional parser support for higher-quality source scanning: - `@astrojs/compiler` — Astro component parsing - `svelte` — Svelte component parsing +## Discovery + +`@contentrain/mcp` is published for both package-based and registry-based MCP discovery: + +- **npm package:** [`@contentrain/mcp`](https://www.npmjs.com/package/@contentrain/mcp) +- **MCP Registry name:** `io.github.Contentrain/contentrain` +- **Local server binary:** `contentrain-mcp` +- **CLI stdio entrypoint:** `contentrain serve --stdio` +- **Hosted remote endpoint:** Contentrain Studio MCP Cloud at `https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp` + +Use the local stdio server when the agent should work against a checkout on your machine. Use Studio MCP Cloud when an external agent should operate a connected Studio project through a project-scoped API key. + ## Tool Catalog The MCP server exposes **19 tools** organized by function. Each tool includes [MCP annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can distinguish safe reads from writes and destructive operations. @@ -303,6 +315,71 @@ This auto-creates the correct MCP config file and installs AI rules/skills. Once connected, the agent has access to all 19 MCP tools and can manage your content through natural language. +### OpenAI Codex + +Codex uses `~/.codex/config.toml` or a trusted project-scoped `.codex/config.toml`. + +```bash +codex mcp add contentrain -- npx -y contentrain serve --stdio +``` + +Equivalent `config.toml`: + +```toml +[mcp_servers.contentrain] +command = "npx" +args = ["-y", "contentrain", "serve", "--stdio"] +``` + +For Studio MCP Cloud, configure a Streamable HTTP server with the project endpoint and Bearer token: + +```toml +[mcp_servers.contentrain] +url = "https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp" +http_headers = { Authorization = "Bearer " } +``` + +### Claude Desktop + +Claude Desktop reads `claude_desktop_config.json`. For a local checkout: + +```json +{ + "mcpServers": { + "contentrain": { + "command": "npx", + "args": ["-y", "contentrain", "serve", "--stdio"] + } + } +} +``` + +For Studio MCP Cloud: + +```json +{ + "mcpServers": { + "contentrain": { + "type": "http", + "url": "https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +### Claude Code + +Claude Code can use the project `.mcp.json` generated by `contentrain setup claude-code`, or add the hosted endpoint directly: + +```bash +claude mcp add --transport http contentrain \ + https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp \ + --header "Authorization: Bearer " +``` + ## Trust Model | Trust Level | Tools | Risk | Notes | diff --git a/docs/packages/rules.md b/docs/packages/rules.md index 3978e32..5b3bf5d 100644 --- a/docs/packages/rules.md +++ b/docs/packages/rules.md @@ -94,7 +94,7 @@ import { } from '@contentrain/rules' // Check if a tool exists -console.log(MCP_TOOLS.length) // 17 +console.log(MCP_TOOLS.length) // 19 console.log(MCP_TOOLS.includes('contentrain_validate')) // true console.log(MCP_TOOLS.includes('contentrain_merge')) // true console.log(MCP_TOOLS.includes('contentrain_doctor')) // true diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 89a8aa4..258c29f 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -3,7 +3,7 @@ "version": "1.8.1", "mcpName": "io.github.Contentrain/contentrain", "license": "MIT", - "description": "Local-first MCP server for AI-generated content governance — 17 deterministic tools, stdio + HTTP transports, Local / GitHub / GitLab providers", + "description": "Local-first MCP server for AI-generated content governance — 19 deterministic tools, stdio + HTTP transports, Local / GitHub / GitLab providers", "type": "module", "repository": { "type": "git", @@ -26,6 +26,8 @@ "local-first", "platform-independent", "claude", + "claude-code", + "codex", "cursor", "windsurf" ], diff --git a/packages/mcp/server.json b/packages/mcp/server.json index db537f8..ef7070e 100644 --- a/packages/mcp/server.json +++ b/packages/mcp/server.json @@ -1,20 +1,44 @@ { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.Contentrain/contentrain", - "description": "Local-first MCP server for AI content governance — models, content, validation, i18n", + "title": "Contentrain", + "description": "Git-native content governance for AI agents — 19 deterministic tools for models, content, validation, normalize, i18n, and review branches.", + "websiteUrl": "https://ai.contentrain.io/packages/mcp", "repository": { "url": "https://github.com/Contentrain/ai", - "source": "github" + "source": "github", + "subfolder": "packages/mcp" }, - "version": "1.0.6", + "version": "1.8.1", "packages": [ { "registryType": "npm", + "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@contentrain/mcp", - "version": "1.0.6", + "version": "1.8.1", "transport": { "type": "stdio" } } + ], + "remotes": [ + { + "type": "streamable-http", + "url": "https://studio.contentrain.io/api/mcp/v1/{project_id}/mcp", + "variables": { + "project_id": { + "description": "Contentrain Studio project ID for the MCP Cloud endpoint.", + "isRequired": true + } + }, + "headers": [ + { + "name": "Authorization", + "description": "Bearer token using a Contentrain Studio MCP Cloud API key.", + "isRequired": true, + "isSecret": true + } + ] + } ] } diff --git a/packages/rules/README.md b/packages/rules/README.md index 94e131c..ee71463 100644 --- a/packages/rules/README.md +++ b/packages/rules/README.md @@ -75,7 +75,7 @@ The package root exports constants for tooling: - `FIELD_TYPES` — 27 flat field types - `MODEL_KINDS` — `singleton`, `collection`, `document`, `dictionary` -- `MCP_TOOLS` — 17 MCP tool names (includes `contentrain_merge` and `contentrain_doctor`) +- `MCP_TOOLS` — 19 MCP tool names (includes `contentrain_merge`, branch lifecycle tools, and `contentrain_doctor`) - `ESSENTIAL_RULES_FILE` — path to essential guardrails markdown - `STACKS` — supported framework stacks @@ -84,7 +84,7 @@ The package root exports constants for tooling: ```ts import { MCP_TOOLS, ESSENTIAL_RULES_FILE, FIELD_TYPES } from '@contentrain/rules' -console.log(MCP_TOOLS.length) // 17 +console.log(MCP_TOOLS.length) // 19 console.log(MCP_TOOLS.includes('contentrain_merge')) // true console.log(MCP_TOOLS.includes('contentrain_doctor')) // true console.log(ESSENTIAL_RULES_FILE) // 'essential/contentrain-essentials.md' diff --git a/packages/skills/README.md b/packages/skills/README.md index d070005..1fd72f1 100644 --- a/packages/skills/README.md +++ b/packages/skills/README.md @@ -127,7 +127,7 @@ This reduces always-loaded context from thousands of lines to just the essential `@contentrain/skills` is kept in lockstep with the MCP tool registry via cross-package parity tests (`tests/mcp-parity.test.ts`): -- `skills/contentrain/references/mcp-tools.md` must have an `### ` heading for every tool in the MCP `TOOL_NAMES` registry (currently 17). +- `skills/contentrain/references/mcp-tools.md` must have an `### ` heading for every tool in the MCP `TOOL_NAMES` registry (currently 19). - Key skills (normalize, translate) must not reference legacy `contentrain/{operation}/...` branch prefixes — MCP now emits `cr/*`. When MCP's surface changes, these tests fail until the skill docs catch up.