/cf-add-integration

name: cf-add-integration
description: "Add a custom MCP connector for any external API or service. \"hook up our internal CMS\""
disable-model-invocation: false
argument-hint: "[service-name]"
effort: medium

/contentforge:cf-add-integration

> **Script location.** If your host does not set `${CLAUDE_PLUGIN_ROOT}`, the scripts are in this plugin's `scripts/` folder, next to `skills/`. Run them with Python 3.10 or newer: `python`, or `python3` where `python` is not found (macOS, many Linux systems).

Execution gate

This skill shows a ready-to-paste `.mcp.json` entry and the credential steps; it does not edit configuration files or store secrets, and it never asks for a secret in the conversation. If the user asks it to write the entry into a file, show the exact change first and write only after an explicit `yes`; any other reply cancels.

Purpose

Help users connect any external API, tool, or service to ContentForge as an MCP connector. Walk through the entire process conversationally — from finding the right MCP package to testing the connection — without requiring technical MCP knowledge.

Input Required

The user provides (or will be asked):

• **What they want to connect**: The service name and what they want it to do — e.g., "Google Analytics to track content performance", "Ahrefs for keyword research", "our internal CMS to publish directly"
• **Credentials**: API keys, tokens, or OAuth setup they have (or will need to obtain). The system will guide them on exactly what's needed. **Never ask users to paste secrets into the conversation.**

Process

Step 1: Understand what the user wants

Ask the user what service they want to connect and what they want it to do within ContentForge. Map their intent to content workflow stages:

| Workflow Stage | Example Integrations | |---------------|---------------------| | Research (Phase 1) | Ahrefs, Similarweb, Google Search Console | | Publishing (Phase 8) | Webflow, WordPress, HubSpot CMS | | Collaboration | Notion, Slack, Google Drive | | Tracking | Google Sheets, Google Analytics | | Translation | DeepL, Sarvam AI | | Social distribution | Twitter/X, LinkedIn, Instagram |

Step 2: Check if a connector already exists

Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/connector-status.py" --action check <name>` to see if the connector is already in the registry.

• **If it exists and is connected**: Tell the user it's already active and which skills use it.
• **If it exists but not connected**: Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/connector-status.py" --action setup-guide <name>` and walk through the guided setup.
• **If it doesn't exist**: Proceed to Step 3.

Step 3: Find an MCP package

Search for an existing MCP server package that provides the desired integration.

Note: ContentForge ships no `.mcp.json` by design — every connector is opt-in and user-added. Nothing is pre-wired.

1. **Check verified HTTP endpoints first** — hosted HTTP MCP servers are the easiest (work in both Cowork and Claude Code, no API keys for OAuth-based ones). The plugin's catalog of verified HTTP endpoints lives in **`.mcp.json.connectors-reference`** — use the URL from that file. If the service isn't listed there, check the vendor's official documentation for an MCP endpoint before guessing. Do not use endpoint URLs from memory: unverified URLs waste the user's setup time.

2. **Do not search npm for a package and do not guess a package name.** `npx -y <name>` runs whatever is published under that name with the user's API keys in its environment, and a name nobody has registered can be registered by anyone. ContentForge gives a runnable command only for packages the service's vendor publishes (`config/verified-npx-packages.json`). If the vendor has no MCP endpoint, offer an aggregator entry from `.mcp.json.connectors-reference`, or a custom server (Step 5). If the user names a specific community package themselves, say plainly that it is an **unverified third party**, run `npm view <package-name> maintainers repository time` and show them the result, and give them an entry only if they still want one: pinned to the exact version they reviewed (`<package-name>@<version>`), with environment-variable references and no values.

3. **If no endpoint or package exists** — Guide the user through custom MCP server development (see Step 5).

Step 4: Configure the connector

Generate the exact configuration entry for `.mcp.json`:

**For HTTP connectors:**

{
  "mcpServers": {
    "service-name": {
      "type": "http",
      "url": "https://mcp.service.com/mcp",
      "description": "Service Name — what it provides for ContentForge"
    }
  }
}

**For npx connectors (a vendor-published package, or one the user named and accepted as unverified):**

{
  "mcpServers": {
    "service-name": {
      "command": "npx",
      "args": ["-y", "<package-name>@<reviewed-version>"],
      "env": {
        "SERVICE_API_KEY": "${SERVICE_API_KEY}"
      },
      "description": "Service Name — what it provides for ContentForge"
    }
  }
}

**Walk the user through:** 1. Open `.mcp.json` in the plugin root directory 2. Add the new entry inside the `mcpServers` object 3. Set up environment variables (explain where: `.env` file or system environment) 4. Save and restart the session

Step 5: Custom MCP server (if needed)

If no existing package covers the user's needs, provide a development template:

Project Structure:
  my-mcp-server/
  ├── index.js          # Main server with tool definitions
  ├── package.json      # Dependencies
  └── .env.example      # Required credentials

Key Components:
  - Tool definitions (what Claude can call)
  - Authentication handler (API key, OAuth, etc.)
  - Request/response formatting
  - Error handling with meaningful messages

.mcp.json Entry:
  "my-service": {
    "command": "node",
    "args": ["path/to/my-mcp-server/index.js"],
    "env": { "MY_API_KEY": "${MY_API_KEY}" }
  }

Provi