extend-mcp-server

Files (1)

• SKILL.md

SKILL.md (first lines)

# Extend an Existing MCP Connector

Guide users through adding new tools to an existing open-source MCP connector in the [`mcp-servers`](https://github.com/mindstone-engineering/mcp-servers) repository.

This skill is for when a user wants to **add a tool to an existing connector** — not build a new one from scratch. If the user wants to build a new connector, redirect to the [build-custom-mcp-server](../build-custom-mcp-server/SKILL.md) skill instead.

**Reference docs** (load as needed):
- [mcp-development-standard.md](../build-custom-mcp-server/references/mcp-development-standard.md) — SDK patterns, naming conventions, error handling, module architecture, security baseline, packaging
- [mcp-testing-guide.md](../build-custom-mcp-server/references/mcp-testing-guide.md) — Test strategy, test patterns, debugging common failures
- [contribute-connector.md](../build-custom-mcp-server/references/contribute-connector.md) — Contributing back to the ecosystem (lifecycle, PR template, quality bar, CI pipeline)
- [community-mcp-security-review.md](../../system/mcp-add-update-remove-connector/references/community-mcp-security-review.md) — Security review process for community MCPs

**Required orchestration workflow** (for Phase 4):
- [Software Engineer workflow](../../workflows/software-engineer/SKILL.md) — Structured coding orchestration (Understand → Plan → Implement → Review → Test & Deliver)


## Contribution State Reporting

Always report build progress at key checkpoints using the `rebel_mcp_report_contribution_state` bundled tool. This tracks the extension in the conversation UI (MCPBuildCard) and offers the user a one-click "Submit to community" option when ready. Call it regardless of whether the user intends to share — it powers local UI, not submission.

If `rebel_mcp_report_contribution_state` is not listed in your available tools, or `session_id` is missing from your `<dynamic_env>` context, skip all state reporting silently.

**Required parameters for every call:**
- `sessionId`: Use the `session_id` value from your `<dynamic_env>` context (must match exactly)
- `connectorName`: The connector name being extended
- `status`: The checkpoint status (see table below)
- `localServerPath` (at `draft` checkpoint): The full path to the local fork build directory

**Extension-specific parameters** (set at `ready_to_submit` checkpoint):
- `prTitle`: Tool-specific PR title, e.g. `feat(<connector>): add <tool_name> tool`. **Required for extension PRs** — without this, the in-app flow defaults to a generic "feat: add connector" title that doesn't reflect the extension scope.
- `prBody`: Tool-specific PR body using the Extension PR Template from Phase 6 below. **Required for extension PRs** — without this, the in-app flow uses a generic description.

**Checkpoints — call `rebel_mcp_report_contribution_state` at each:**

| When | Status | Notes |
|------|--------|-------|
| After Phase 4 (Implementation complete) | `draft` | New tool implemented and tests written |
| Start of Phase 5 (Local testing begins) | `testing` | Building and running in Rebel locally |
| After Phase 5 (Local testing passes) | `ready_to_submit` | Include `prTitle` and `prBody` for the extension PR |


## Process Overview

```
Phase 1: Eligibility Gate      → Verify the connector can be extended
Phase 2: Prepare Workspace     → Set up a local workspace for development (silent, no user questions)
Phase 3: Connector Research    → Understand existing patterns and where the new tool fits
Phase 4: Implementation        → Delegate coding to Software Engineer workflow
Phase 5: Run Locally in Rebel  → Configure Rebel to use the local build
Phase 6: Submit Extension      → In-app contribution or manual PR
```


## Phase 1: Eligibility Gate

Before any development, determine whether the connector can be extended through this flow.

### 1.1 Identify the Connector

Ask: "Which connector do you want to extend, and what tool do you want to add?"

Get:
- The **connector name** (e.g., "Zendesk", "Slack", "Google Workspace")
- The **tool being added** (e.g., "search macros", "list channels", "create calendar event")
- **Why the existing tools are insufficient** for the user's needs

### 1.2 Determine Connector Location

Check where the connector lives. There are three possible paths.

**The `bundled-` ID prefix is NOT a classifier.** Many connectors with `bundled-*` IDs are fully open-source (`provider: "rebel-oss"`, Path A), while others are truly internal (`provider: "bundled"`, Path B). The only signal that matters is the `provider` field from the live catalog.

---

#### Step 1 — Preferred: call the catalog tool

Call `rebel_mcp_get_connector` (by ID, stripping any `catalog:` prefix) or `rebel_mcp_search_connectors` (by name). Quote the `provider` field verbatim in your response (e.g., "Catalog says: `provider: "rebel-oss"`"). The quoted value is what decides the path.

Then assign the path:
- `provider: "rebel-oss"` → **Path A** (open-source, extendable)
- `provider: "bundled"` → **Path B** (truly bundled/internal, not extendable)
- Any other or missing `provider` → **Path C** (third-party)

**Do NOT** read `resources/connector-catalog.json` from disk — there may be stale copies on the filesystem. The MCP tools are the single source of truth when available.

---

#### Step 2 — Fallback: the bundled-* deterministic allowlist

Use this ONLY when the catalog tool is genuinely unavailable in your tool list (e.g., running in a planning-only phase that has no MCP tools). When the tool IS available, Step 1 takes precedence.

The following `bundled-*` IDs are `provider: "rebel-oss"` → **Path A (extendable)**. This list is validated against `resources/connector-catalog.json` by `scripts/check-extend-skill-bundled-allowlist.ts` — if it drifts, the validator fails.

<!-- BUNDLED_REBEL_OSS_ALLOWLIST_START -->
```yaml
# provider: "rebel-oss" connectors with bundled-* IDs (Path A — extendable)
bundled_rebel_oss_ids:
  - bundled-alibaba-mail
  - bundled-alibaba-mail-personal
  - bundled-apple-shortcuts
  - bundled-browser-automation
  - bundled-browserbase
  - bundled-custom-email
  - bundled-elevenlabs
  - bundled-elevenlabs-agents
  - bundled-fathom
  - bundled-freshdesk
  - bundled-gamma
  - bundled-google
  - bundled-google-analytics
  - bundled-hubspot
  - bundled-humaans
  - bundled-icloud-mail
  - bundled-kling
  - bundled-microsoft-calendar
  - bundled-microsoft-files
  - bundled-microsoft-mail
  - bundled-microsoft-sharepoint
  - bundled-microsoft-teams

From mindstone/rebel-system, MIT.

More from mindstone/rebel-system