Skip to content

indranilbanerjee/digital-marketing-pro / skills/context-engine

context-engine

Verified

Load shared marketing context: brand profile, benchmarks, compliance rules, specs. "load my brand context"

FileKindSize
30-60-90-framework.mdmarkdown8.2 KB
SKILL.mdskill md12.9 KB
actionable-persona-format.mdmarkdown7.0 KB
advanced-reporting-guide.mdmarkdown21.1 KB
agency-operations-guide.mdmarkdown15.7 KB
ai-visibility-metrics.mdmarkdown2.9 KB
approval-framework.mdmarkdown13.0 KB
b2b-decision-making-unit.mdmarkdown9.1 KB
channel-families.mdmarkdown7.7 KB
competitive-monitoring-guide.mdmarkdown16.8 KB
competitor-3-question-output.mdmarkdown8.0 KB
compliance-rules.mdmarkdown87.2 KB
compound-intelligence-guide.mdmarkdown15.5 KB
creative-intelligence-guide.mdmarkdown13.9 KB
crm-integration-guide.mdmarkdown35.4 KB
custom-mcp-guide.mdmarkdown17.1 KB
decision-framework.mdmarkdown7.4 KB
decision-matrix-rerun.mdmarkdown4.9 KB
engagement-flow-methodology.mdmarkdown11.4 KB
eu-code-of-practice.mdmarkdown15.6 KB
eval-framework-guide.mdmarkdown27.5 KB
eval-rubrics.mdmarkdown16.8 KB
execution-workflows.mdmarkdown23.3 KB
five-digital-markets.mdmarkdown7.5 KB
fixed-vs-variable-budget.mdmarkdown6.8 KB
four-core-documents-spec.mdmarkdown14.2 KB
geo-execution-guide.mdmarkdown20.2 KB
google-seo-reference.mdmarkdown7.3 KB
growth-plan-template.mdmarkdown9.5 KB
guidelines-framework.mdmarkdown14.0 KB
in-market-out-market.mdmarkdown6.1 KB
india-market-context.mdmarkdown14.1 KB
industry-profiles.mdmarkdown65.0 KB
intelligence-layer.mdmarkdown3.9 KB
journey-growth-guide.mdmarkdown19.8 KB
living-instruction-file-spec.mdmarkdown7.2 KB
market-intelligence-guide.mdmarkdown13.7 KB
marketing-science-guide.mdmarkdown14.0 KB
memory-architecture.mdmarkdown12.5 KB
monthly-report-template.mdmarkdown7.0 KB
multilingual-execution-guide.mdmarkdown31.7 KB
narrative-warfare-guide.mdmarkdown17.9 KB
platform-publishing-specs.mdmarkdown19.5 KB
platform-specs.mdmarkdown34.7 KB
reporting-cadence.mdmarkdown8.5 KB
schema-templates.jsonconfig8.7 KB
scoring-rubrics.mdmarkdown10.9 KB
self-healing-ops-guide.mdmarkdown18.5 KB
seo-execution-guide.mdmarkdown14.8 KB
stone-vs-opinion.mdmarkdown7.7 KB
synthetic-audience-guide.mdmarkdown20.4 KB
team-roles-framework.mdmarkdown12.4 KB
three-scenario-forecasting.mdmarkdown7.4 KB
transcreation-framework.mdmarkdown24.2 KB
two-views-model.mdmarkdown5.5 KB
unit-economics-framework.mdmarkdown7.5 KB
update-back-rule.mdmarkdown7.0 KB
yearly-planner-template.mdmarkdown6.1 KB

custom-mcp-guide.md

View on GitHub
# Custom MCP Integration Guide — Adding & Building MCP Servers

## What MCPs Are

Model Context Protocol (MCP) servers connect Claude to external services. Each MCP provides **tools** (functions Claude can call), **resources** (data Claude can read), and **prompts** (pre-defined interaction templates). MCP servers run as separate processes that communicate with Claude via JSON-RPC over stdin/stdout.

In this plugin, MCPs are the execution bridge between the agent layer (Claude reasoning about marketing strategy) and external platforms (publishing a blog post, sending an email campaign, querying a CRM). **`.mcp.json` ships empty by design** (`{"mcpServers":{}}` — nothing auto-connects, which keeps Cowork and team installs safe). Vendor-hosted HTTP servers are listed in `.mcp.json.connectors-reference`; `.mcp.json.example` holds runnable entries only for packages the vendor itself publishes on npm, pinned to an exact version. Copy the entries you need into your own `.mcp.json`; this guide shows how to add or build servers beyond the catalog.

---

## How MCPs Work in This Plugin

### Configuration

Your `.mcp.json` (project or user scope) defines the MCP server configurations you have opted into. Claude discovers available MCPs at session start and can call their tools during a session. (The plugin's own `.mcp.json` ships empty — start from `.mcp.json.example`.)

**`.mcp.json` schema:**
```json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "<vendor-package>@<exact-version>"],
      "env": {
        "API_KEY": "${ENV_VAR_NAME}"
      },
      "description": "What this server provides"
    }
  }
}
```

### Key Mechanics

- **`command`**: The executable to run — typically `npx` (for npm packages), `node` (for local scripts), or `python` (for Python-based MCPs)
- **`args`**: Arguments passed to the command — the package pinned to an exact version for npx (`<package>@x.y.z`), file path for node/python
- **`env`**: Environment variables injected into the MCP process — use `${VAR_NAME}` syntax to reference variables from `.env` or the shell environment
- **`description`**: Human-readable explanation that helps Claude understand when to use this MCP

### How Claude Uses MCPs at Runtime

1. **Session start:** Claude reads `.mcp.json` and starts configured MCP servers
2. **Tool discovery:** Claude calls `tools/list` on each server to learn available tools
3. **Tool invocation:** During conversation, Claude calls MCP tools by name with JSON parameters
4. **Safety gate:** Claude Code's own permission system prompts before tool calls per your settings. This plugin ships no hook for MCP tools (its one hook gates only its own live-write scripts; plugin hooks fire globally); follow the read/write tool-naming convention below so write operations are recognizable, and rely on the built-in permission prompts for approval
5. **Response:** MCP server executes the operation and returns results to Claude

---

## Adding an Existing MCP Package

### Step-by-Step

1. **Identify the service** you want to connect (e.g., Mailchimp, HubSpot, Airtable)

2. **Find the vendor's own server:** first a hosted HTTP MCP endpoint (see `.mcp.json.connectors-reference` for verified ones), then an npm package, accepted only when the package's publisher is the vendor's own npm account and its repository is in the vendor's own organisation (check `https://registry.npmjs.org/<package>`: `maintainers` and `repository`). A community package, or a name nobody has published, can be published by anyone and would receive your API keys; if the vendor publishes nothing, build your own server (below)

3. **Test the package locally:**
   ```bash
   npx -y <vendor-package>@<exact-version> --help
   ```

4. **Add to `.mcp.json`:**
   ```json
   {
     "mcpServers": {
       "mailchimp": {
         "command": "npx",
         "args": ["-y", "<vendor-package>@<exact-version>"],
         "env": {
           "MAILCHIMP_API_KEY": "${MAILCHIMP_API_KEY}",
           "MAILCHIMP_SERVER_PREFIX": "${MAILCHIMP_SERVER_PREFIX}"
         },
         "description": "Mailchimp email marketing — list management, campaign creation, audience segmentation"
       }
     }
   }
   ```

5. **Add credentials to `.env`:**
   ```
   MAILCHIMP_API_KEY=your-api-key-here
   MAILCHIMP_SERVER_PREFIX=us14
   ```

6. **Verify connectivity:** Start a new Claude session and ask Claude to list available tools from the new MCP

7. **Document:** Update `docs/integrations-guide.md` with the new integration

### Pre-Flight Checklist

- [ ] The package is published by the vendor itself (npm `maintainers` and `repository` belong to the vendor), not a community fork or look-alike name
- [ ] `args` pins an exact version (`<package>@x.y.z`), never a bare name or `latest`
- [ ] Required credentials are available (API key, OAuth tokens, etc.)
- [ ] Credentials added to `.env` with correct variable names
- [ ] `.mcp.json` entry uses `${VAR}` syntax for all secrets (never hardcode credentials)
- [ ] Server starts without error in a new session
- [ ] `tools/list` returns expected tools
- [ ] Read operations return valid data
- [ ] Write operations trigger the approval hook correctly

---

## Environment Variable Conventions

### Naming Standards

| Type | Pattern | Example |
|---|---|---|
| **API Key** | `{SERVICE}_API_KEY` | `MAILCHIMP_API_KEY`, `HUBSPOT_API_KEY` |
| **Base URL** | `{SERVICE}_URL` | `ODOO_URL`, `CUSTOM_API_URL` |
| **OAuth Client ID** | `{SERVICE}_CLIENT_ID` | `GOOGLE_CLIENT_ID`, `META_CLIENT_ID` |
| **OAuth Client Secret** | `{SERVICE}_CLIENT_SECRET` | `GOOGLE_CLIENT_SECRET` |
| **Access Token** | `{SERVICE}_ACCESS_TOKEN` | `SLACK_ACCESS_TOKEN`, `NOTION_ACCESS_TOKEN` |
| **Server/Region** | `{SERVICE}_SERVER_PREFIX` | `MAILCHIMP_SERVER_PREFIX`, `AWS_REGION` |
| **Database** | `{SERVICE}_DB_NAME` | `POSTGRES_DB_NAME`, `MONGO_DB_NAME` |

### Storage Rules

- **All credentials** go in `.env` at the project root — never in `.mcp.json`, never in scripts, never committed to git
- **`.env` is gitignored** — verify this before any commit
- **Agency mode:** Per-client credentials stored at `~/.claude-marketing/credentials/{profile-name}.json` (see Credential Profiles section below)
- **Rotation:** Rotate API keys quarterly. Use short-lived tokens (OAuth) where possible.

---

## Building a Custom MCP Server

When no existing package covers your service, build a custom MCP server.

### Project Setup

```bash
mkdir mcp-server-yourservice
cd mcp-server-yourservice
npm init -y
npm install @modelcontextprotocol/sdk zod
```

### Minimal Server Template

```javascript
#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "yourservice",
  version: "1.0.0",
  description: "MCP server for YourService — describe what it provides",
});

// --- Read Tool (your host's permission settings decide whether it prompts) ---
server.tool(
  "list_items",
  "List all items from YourService",
  { status: z.enum(["active", "archived", "all"]).optional() },
  async ({ status }) => {
    const response = await fetch(`${process.env.YOURSERVICE_URL}/api/items?status=${status || "active"}`, {
      headers: { "Authorization": `Bearer ${process.env.YOURSERVICE_API_KEY}` },
    });
    const data = await response.json();
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

// --- Write Tool (the host prompts for it unless you allow it; keep writes out of your allowlist) ---
server.tool(
  "create_item",
  "Create a new item in YourService",
  { name: z.string(), description: z.string().optional() },
  async ({ name, description }) => {
    const response = await fetch(`${process.env.YOURSERVICE_URL}/api/items`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.YOURSERVICE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ name, description }),
    });
    const data = await response.json();
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

// --- Start Server ---
const transport = new StdioServerTransport();
await server.connect(transport);
```

### Adding to `.mcp.json` (Local Server)

```json
{
  "mcpServers": {
    "yourservice": {
      "command": "node",
      "args": ["path/to/mcp-server-yourservice/index.js"],
      "env": {
        "YOURSERVICE_URL": "${YOURSERVICE_URL}",
        "YOURSERVICE_API_KEY": "${YOURSERVICE_API_KEY}"
      },
      "description": "YourService integration — item management, data queries"
    }
  }
}
```

---

## Naming Conventions

### Server Naming

| Item | Convention | Example |
|---|---|---|
| **`.mcp.json` key** | lowercase-kebab-case, matching service | `"mailchimp"`, `"google-sheets"`, `"hubspot-crm"` |
| **npm package** | `mcp-server-{service}` or `@scope/mcp-server-{service}` | `mcp-server-mailchimp`, `@company/mcp-server-crm` |
| **Tool names** | `{action}_{noun}` — verb_object pattern | `list_campaigns`, `create_contact`, `send_email`, `get_report` |
| **Resource URIs** | `{service}://{resource-type}/{id}` | `mailchimp://lists/abc123`, `hubspot://contacts/456` |

### Tool Naming for Read vs Write Classification

Name tools so their side effects are obvious from the prefix — Claude Code's permission prompts (and any user-scope hooks you add yourself) can then treat reads and writes differently:

| Prefix | Classification | Recommended handling |
|---|---|---|
| `list_`, `get_`, `query_`, `search_`, `fetch_`, `count_` | **Read** | Safe to allow |
| `create_`, `update_`, `delete_`, `send_`, `publish_`, `schedule_`, `import_`, `sync_` | **Write** | Require explicit approval |

**Always name your tools using these prefixes** so read/write intent is machine-recognizable. If a tool has side effects, use a write prefix even if it also reads data. (This plugin ships no hook for MCP tools — approval gating for them comes from Claude Code's own permission system.)

---

## Common Integration Patterns

### Pattern 1: REST API Wrapper (Most Common)

Map REST endpoints directly to MCP tools:

| REST Endpoint | MCP Tool | Type |
|---|---|---|
| `GET /api/contacts` | `list_contacts` | Read |
| `GET /api/contacts/:id` | `get_contact` | Read |
| `POST /api/contacts` | `create_contact` | Write |
| `PUT /api/contacts/:id` | `update_contact` | Write |
| `DELETE /api/contacts/:id` | `delete_contact` | Write |
| `GET /api/contacts/search?q=` | `search_contacts` | Read |

**Pagination:** Implement cursor-based pagination within the tool. Accept `page` or `cursor` parameter, return results + next cursor.

### Pattern 2: GraphQL Wrapper

For GraphQL APIs, create a single flexible query tool plus specific mutation tools:

- `query_data` — accepts GraphQL query string, returns results (read)
- `create_record` — specific mutation with typed inputs (write)
- `update_record` — specific mutation with typed inputs (write)

### Pattern 3: Webhook Receiver

For event-driven integrations:
- Register webhooks via a `register_webhook` tool (write, one-time setup)
- MCP server listens for incoming events and surfaces them as resources
- Claude reads events via `get_recent_events` tool (read)

### Pattern 4: Database Connector

- `query_database` — parameterized SQL/NoSQL query (read)
- `insert_record` / `update_record` — typed data mutations (write)
- **Always default to read-only.** Write access should require explicit configuration.

---

## Credential Profiles for Agency Mode

In agency mode, different clients use different credentials for the same services (e.g., each client has their own Mailchimp account).

### Profile Structure

Stored at `~/.claude-marketing/credentials/{profile-name}.json`:

```json
{
  "profile_name": "acme-corp",
  "created_at": "2026-01-15T10:00:00Z",
  "credentials": {
    "mailchimp": {
      "MAILCHIMP_API_KEY": "key-us14-abc123",
      "MAILCHIMP_SERVER_PREFIX": "us14"
    },
    "hubspot": {
      "HUBSPOT_API_KEY": "pat-na1-xyz789"
    },
    "google-analytics": {
      "GA_PROPERTY_ID": "123456789"
    }
  }
}
```

### How Profile Switching Works

1. User runs `/digital-marketing-pro:credential-switch --profile acme-corp`
2. `credential-manager.py` loads the profile JSON
3. Environment variables are injected for the session
4. MCP servers restart with the new credentials
5. All subsequent MCP calls use the client's accounts

### Security Rules for Profiles

- [ ] Profile files are stored outside the plugin directory (in `~/.claude-marketing/`)
- [ ] Profile files are never committed to git
- [ ] Each profile only contains credentials for services that client uses
- [ ] API keys in profiles are encrypted at rest (if using `credential-manager.py` encryption feature)
- [ ] Profile access is logged — `credential-manager.py` records which profile was loaded and when

---

## Testing a New MCP Integration

### Testing Checklist

| Test | How to Verify | Pass Criteria |
|---|---|---|
| **Server starts** | Start new Claude session, check for errors | No startup errors in console |
| **Tool discovery** | Ask Claude "What tools are available from [server]?" | Expected tools appear in list |
| **Read operations** | Call a list/get tool with known data | Returns valid, formatted data |
| **Write operations** | Attempt a create/update tool | Approval hook fires, then operation succeeds |
| **Missing credentials** | Remove API key from `.env`, restart | Clear error message, not a crash |
| **Invalid credentials** | Use wrong API key | Structured error response, not a crash |
| **Rate limiting** | Rapid successive calls (if safe to test) | Graceful error with retry guidance |
| **Large responses** | Query that returns 100+ items | Paginated or truncated cleanly |
| **Error handling** | Invalid input parameters | Structured error with field-level detail |

### Debugging

- **MCP server logs:** Check stderr output from the MCP process for error traces
- **Network issues:** Verify the API base URL and that outbound requests are not blocked
- **Auth failures:** Confirm the env var name in `.mcp.json` exactly matches the var name in `.env`
- **Tool not appearing:** Verify the server key in `.mcp.json` is valid JSON and the tool is registered before `server.connect()`

---

## Security Considerations

### Credential Safety

- **Never** store credentials directly in `.mcp.json` — always use `${VAR}` references
- **Never** log API keys or tokens in MCP server output
- **Rotate** API keys quarterly at minimum, immediately if compromised
- **Scope** API keys to minimum required permissions (read-only where possible)
- **Audit** MCP tool calls via execution logs (`execution-tracker.py` logs all tool invocations)

### Access Control

- Claude Code's permission system is the primary safety gate — configure allow/deny rules for MCP tools in your settings (this plugin's one hook covers only its own live-write scripts; add user-scope hooks yourself if you want automated gating of MCP tools)
- Treat read tools (list, get, query, search, fetch) as safe to allow
- Require explicit user approval for write tools (create, update, delete, send, publish, schedule)
- Custom MCPs **must** follow the naming convention so read/write intent is recognizable
- If a tool performs both read and write operations, classify it as write (use a write prefix)

### Supply Chain

- Prefer well-maintained MCP packages with 1,000+ npm weekly downloads
- Pin package versions in production (avoid `latest` tag)
- Review package source code before deploying, especially for packages with `< 100` downloads
- For sensitive integrations (CRM, payment, auth), build custom MCPs rather than using third-party packages

---

## Example Configurations

### Odoo ERP (REST/JSON-RPC)

```json
{
  "odoo": {
    "command": "node",
    "args": ["path/to/mcp-server-odoo/index.js"],
    "env": {
      "ODOO_URL": "${ODOO_URL}",
      "ODOO_DB": "${ODOO_DB}",
      "ODOO_USERNAME": "${ODOO_USERNAME}",
      "ODOO_API_KEY": "${ODOO_API_KEY}"
    },
    "description": "Odoo ERP — contacts, invoices, products, sales orders"
  }
}
```

### Generic REST API

```json
{
  "custom-api": {
    "command": "node",
    "args": ["path/to/mcp-server-rest/index.js"],
    "env": {
      "REST_BASE_URL": "${CUSTOM_API_URL}",
      "REST_API_KEY": "${CUSTOM_API_KEY}",
      "REST_AUTH_TYPE": "bearer"
    },
    "description": "Custom REST API — generic CRUD operations against your API"
  }
}
```

### Zapier MCP (hosted)

Zapier's current agent integration is **Zapier MCP** (the successor to the retired Natural Language Actions product). Generate your personal MCP endpoint URL at https://mcp.zapier.com and add it as an HTTP server:

```json
{
  "zapier": {
    "type": "http",
    "url": "https://mcp.zapier.com/api/mcp/mcp",
    "headers": {
      "Authorization": "Bearer ${ZAPIER_MCP_TOKEN}"
    },
    "description": "Zapier MCP — trigger Zaps and AI Actions, connect 5000+ apps"
  }
}
```

> **Key principle:** Every MCP integration should be tested with both valid and invalid credentials, should handle errors gracefully with structured responses, and should follow the read/write naming convention so permission gating stays reliable. When in doubt, classify a tool as write — it is always safer to require approval than to allow unintended side effects.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall