菜单
Helps users connect and use a service in Rebel when it isn't already in the built-in connector catalog. Acts as an expert advisor — runs the full build-vs-buy check (catalog, MCP Registry, community) before scaffolding a custom MCP server and guiding research, implementation, security review, and contribution.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Add, update, or remove connectors (MCP servers) in Rebel. Searches the built-in connector catalog first before suggesting custom builds. Handles setup, configuration, and security review for community connectors.
Capture citable sources (meetings, documents, files, media, web content) as structured files in memory/sources/ with provenance metadata for traceability.
Rules for writing error messages, toasts, banners, and recovery copy in Rebel's voice — dry, calm, helpful, and never apologetic. Use whenever you add or rewrite any user-facing error string.
Guides users through adding new tools or capabilities to an existing connector (MCP server). Handles eligibility, workspace setup, connector research, implementation via Software Engineer workflow, local testing, and PR submission with an extension-specific template.
Help users celebrate impactful wins and surface important learnings by analyzing their recent communications and activities.
Guidelines for maintaining single sources of truth and using signposting to connect documentation without duplication
| name | build-custom-mcp-server |
| description | Helps users connect and use a service in Rebel when it isn't already in the built-in connector catalog. Acts as an expert advisor — runs the full build-vs-buy check (catalog, MCP Registry, community) before scaffolding a custom MCP server and guiding research, implementation, security review, and contribution. |
| use_cases | ["Build a connector for [service name]","Build me a connector","I want to add a new connector","Connect my company's internal API to Rebel","Build an MCP for our CRM/ERP/ticketing system","Create tools so Rebel can access our database","Make a connector for a public API","Build an integration for any external service","Create a custom connector from scratch","I need Rebel to talk to [service]","[Service] isn't in the connector catalog","There's no connector for [service]","I want to use [service] in Rebel","I want [service] in Rebel","How do I get [service] working in Rebel?","Can I get [service] working in Rebel?","How do I use [service] in Rebel?","Is there a Rebel connector for [service]?"] |
| last_updated | "2026-04-23T00:00:00.000Z" |
| tools_required | [] |
| agent_type | main_agent |
| license | LICENSE.txt |
Guide users through creating a custom MCP server to connect their API to Rebel.
Default: TypeScript/Node.js using the bundled starter template. Python reference available in references/python_mcp_server.md if requested.
The user is non-technical. They are creating a tool with Rebel, not coding, shipping packages, or managing open-source plumbing. Keep chat copy plain, calm, and about what the tool lets them do.
Forbidden vocabulary in chat: PR, pull request, fork, branch, repo, repository, npm, MCP, MCP server, connector (prefer tool), Phase N, ready_to_submit, testing_evidence, Definition of Done, DoD, CI, automated checks (prefer "checks"), package, OpenAPI, Swagger, Postman, curl, endpoint, payload, HTTP, API (prefer "their service" or the specific verb).
Allowed exceptions:
GitHub is OK only when the user has explicitly chosen the GitHub-attributed path, such as the attribution sub-card.Pronouns:
Action-oriented rule: never ask the user for technical input or permission for technical actions. Do not say "Adding a connector is a protected admin action — may I proceed?" Skill invocation is consent for this flow.
Translate internal action codes before speaking:
| Internal action code | Chat-safe phrasing |
|---|---|
run_tests | I need to try it properly before sharing. |
register_server | I need to connect it to Rebel first. |
move_to_canonical_path | I need to move the files into the right folder before sharing. |
reauth_github | Please reconnect GitHub in Settings → Connectors so we can send it out. |
run_software_engineer_workflow | Let me think this through properly before I share it. |
missing_evidence | I got ahead of myself. Trying it properly now. |
Reference docs (load as needed):
~/mcp-servers/<api-name>-mcp/Before implementation, understand how to design tools for AI agents:
Build for Workflows, Not Just API Endpoints:
schedule_event that checks availability AND creates event)Optimize for Limited Context:
Design Actionable Error Messages:
Use Evaluation-Driven Development:
// internal — do not narrate to user
MANDATORY — You MUST call
rebel_mcp_report_contribution_stateafter building the connector. This is not optional. The moment you finish writing the connector code (all source files created, build succeeds), call this tool withstatus: "draft". This triggers the MCPBuildCard UI that lets the user share their connector with the community. Without this call, the build card never appears and the contribution flow is broken.
Always report build progress using the rebel_mcp_report_contribution_state bundled tool. This tracks the build 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 (e.g. typeform-mcp)status: The checkpoint status (see table below)localServerPath (required at draft and ready_to_submit checkpoints): The full path to the built connector directory (e.g. ~/mcp-servers/typeform-mcp). Tilde-prefixed paths are expanded automatically. The same path you wrote to disk is fine — case and trailing slash don't matter.PR metadata parameters (set at ready_to_submit checkpoint):
prTitle: Connector-specific PR title, e.g. feat: add <api-name> connector. Required — without this, the in-app flow defaults to a generic title.prBody: Rich PR description using the PR Description Template from contribute-connector.md. Required — without this, the in-app flow uses a generic one-liner that gives reviewers no context. See the ready_to_submit checkpoint in Phase 6 for the full template and instructions.State machine:
draft → testing → ready_to_submit → submitted → ci_pass/ci_fail
→ changes_requested → (re-submit)
→ approved → published
→ rejected
Checkpoints — call rebel_mcp_report_contribution_state at each (if tool available):
| When | Status | Call tool? |
|---|---|---|
| After Phase 4 (Implementation complete) | draft | Yes |
| Start of Phase 6 (Testing begins) | testing | Yes |
| After Phase 6 (Tests pass) | ready_to_submit | Yes — include prTitle and prBody |
| User clicks "Submit" in MCPBuildCard | submitted | Handled by in-app contribution service |
| CI result arrives | ci_pass / ci_fail | Handled by contributionStatusService |
| Maintainer reviews | approved / changes_requested | Handled by contributionStatusService |
| npm publish completes | published | Handled by catalog sync workflow |
// internal — do not narrate to user
Phase 0: Build-vs-Buy Gate → Classify intent (add/build/extend), 3-tier check for build, confirm
Phase 1: Discovery → Understand API, use cases, auth method
Phase 2: Research → Find/analyze API documentation
Phase 3: Planning → Design tools, get user approval
Phase 4: Implementation → Delegate coding to Software Engineer workflow
Phase 5: Security → Credential scan, npm audit, security review
Phase 6: Testing → Build, configure Rebel, test interactively
Phase 7: Quality Review → Final quality checklist (post-ready_to_submit)
Phase 8: Submit to Community → Guide user to click "Add to the community" in the MCPBuildCard
Before building anything, determine what the user wants to do and systematically check whether a suitable MCP server already exists. Building a custom MCP is a significant investment — an existing connector that covers 80% of the user's needs is almost always the better choice.
If this conversation was started via the in-app "Set up a connector" button (the rebel_mcp_report_contribution_state tool is available, or the opening message matches the seeded pattern like "I want to build a new connector"), the user has already decided to build. Skip intent classification and the multi-tier build-vs-buy check.
If a service name was provided in the seeded message (e.g., "I want to build a new connector for Zendesk"):
If no service name was provided (e.g., "I want to build a new connector"):
What would you like to connect to Rebel?
Just type the name of the service. If you have a link to anything useful, send that too.
Do not ask about intent (add/build/extend), present numbered options, or run the full 0.0 classification for seeded conversations.
Skip this section for seeded conversations — see 0.0 Seeded Conversation Fast-Path above.
First, classify the user's intent into one of three categories. Route immediately when intent is clear — do not run the 3-tier check for add-intent requests.
ADD intent — the user wants to connect an existing service, not write code:
BUILD intent — the user explicitly wants to create a new MCP server:
Ambiguous intent — could be either add or build:
EXTEND intent — the user wants to add a tool to an existing connector:
If the user wants to ADD A TOOL to an existing connector (e.g., "I want to add search macros to the Zendesk connector", "Add a list channels tool to the Slack MCP", "Extend the Google Workspace connector"):
Determine where the connector lives and route accordingly:
a) Connector is in the mcp-servers repo — The connector's source code is in the open-source [mcp-servers](https://github.com/mindstone/mcp-servers) repository under connectors/<name>/.
→ Redirect to the extend-mcp-server skill. It handles the full extension flow: eligibility check, fork/clone, connector research, implementation, local testing, and PR submission. Stop here — do not proceed with this skill.
b) Connector is bundled/internal (not yet externalized) — The connector is built into Rebel but hasn't been open-sourced to the mcp-servers repository.
→ Tell the user:
"The [tool name] isn't available to change directly yet. I can make a companion [service] tool that runs alongside it and fills in the gaps."
If the user agrees, proceed with this skill (0.1 onwards) to build the companion MCP.
c) Third-party connector — The connector was built by a third party and is not in the mcp-servers repository.
→ Tell the user:
"The [tool name] was made by someone else. If it's public, a developer could suggest changes to them directly, or I can make a companion [service] tool that runs alongside it."
If the user wants to build a companion MCP, proceed with this skill (0.1 onwards).
The following 3-tier check applies when the user wants to build a new connector. If the user is extending an existing connector, they've already been redirected above.
Invariants — never skip these:
- Never skip Tier 1. Always check the Rebel connector catalog first, even if the user is confident nothing exists.
- Always present findings. Show the user what was found at each tier before moving on.
- Explicit confirmation required. The user must explicitly confirm they want to build before proceeding to Phase 1.
- Tool failures are not zero results. If a tier's lookup fails (WebSearch
isError, DNS failure, HTTP error) rather than returning empty results, mark that tierSEARCH_FAILEDinternally — do not summarise it as "nothing found". Retry once with a variant query; if still failing, explain in the Phase 0 summary that this check could not be completed and require explicit user confirmation to proceed despite incomplete evidence.
Skip this if the service name is already known (from a seeded conversation or the user's opening message).
Ask a single free-text question — no multiple-choice options, no categories:
"What service do you want to connect to Rebel? Just type the name (e.g., 'Zendesk', 'Stripe', 'our internal CRM')."
Do NOT ask whether the API is public, internal, SaaS, etc. — you determine that from context later (see 0.7). The user just needs to provide a name.
Search Rebel's built-in connector catalog using the rebel_mcp_search_connectors tool:
rebel_mcp_search_connectors(query: "<service name>")
Also try variations — abbreviations, parent company names, alternative product names (e.g., search "Google" if user says "Gmail", search "Microsoft" if user says "Outlook").
If a matching connector is found:
Present the result to the user:
"Rebel already has a [service] tool that supports [brief capability summary]. You can set it up in Settings — no need to make a new one."
→ Off-ramp: Redirect to the mcp-add-update-remove-connector skill to guide setup. Stop here — do not proceed to Tier 2.
If no match is found:
Tell the user:
"Rebel doesn't already have a [service] tool. I'll check whether someone else has made one."
→ Proceed to Tier 2.
Search the official MCP Registry at registry.modelcontextprotocol.io for existing community MCP servers:
Use web search: site:registry.modelcontextprotocol.io "<service name>"
Also search directly: https://registry.modelcontextprotocol.io with the service name.
Evaluate any results found:
If a suitable MCP server is found:
Present the finding to the user with a brief assessment:
"I found [tool name] that may already do this. It [brief capability summary]. It was made by [author] and was last updated [date]."
"I'll check it's safe before adding it. You can skip that check if you prefer."
→ Off-ramp: If the user agrees, redirect to the mcp-add-update-remove-connector skill. Default to running the community MCP security review process — only skip if the user explicitly opts out. When handing off to the ADD skill, note: "This MCP was found via the MCP Registry — run the security review by default." Stop here — do not proceed to Tier 3.
If nothing suitable is found:
Tell the user:
"Nothing suitable there either. I'll do one broader search."
→ Proceed to Tier 3.
Search npm and GitHub for community MCP servers:
Web search: "<service name> mcp server" npm OR github
Web search: "@modelcontextprotocol <service name>"
Look for:
Evaluate any results found using the same criteria as Tier 2 (use cases, maintenance, documentation, reputation).
If a promising MCP server is found:
Present the finding to the user:
"I found [tool name] that may already do this. It [brief capability summary]. [Quality assessment — maintenance status, stars, last update]."
"I'll check it's safe before adding it. You can skip that check if you prefer."
→ Off-ramp: If the user agrees, redirect to the mcp-add-update-remove-connector skill. Default to running the community MCP security review process — only skip if the user explicitly opts out. When handing off to the ADD skill, note: "This MCP was found via web search — run the security review by default." Stop here.
If nothing suitable exists at any tier:
Tell the user:
"I've checked Rebel's built-in options and looked around. There doesn't seem to be an existing [service] tool that fits your needs. Making one is the right approach."
→ Proceed to the confirmation gate (0.5).
The user must explicitly confirm they want to build before proceeding to Phase 1.
Present a summary of what was checked:
Build-vs-buy summary for [service]:
- ❌ Rebel: No built-in tool found
- ❌ Existing-tool search: [No results / Results found but didn't fit because X / ⚠️ couldn't check]
- ❌ Wider web search: [No results / Results found but didn't fit because X / ⚠️ couldn't check]
"Ready to make your [service] tool? You don't need to know how the wiring works — that's my job."
If any tier is marked SEARCH_FAILED internally, explicitly flag that the search is incomplete and ask the user whether to (a) wait and retry, or (b) proceed knowing an existing tool may exist but wasn't verifiable. Do not proceed silently.
Do not proceed to Phase 1 until the user confirms.
If the user hesitates or wants to reconsider, remind them they can revisit any tier result and add an existing MCP instead.
Once the user has confirmed they want to build:
Run: node --version
Determine from context whether the API is public or internal. Well-known services (Typeform, Stripe, GitHub, etc.) are public. "Our API", "internal CRM", "behind VPN" indicate private.
Only ask the user if the API type is genuinely unclear.
Gather essential information from user:
Ask: "What should Rebel be able to do with [service]? Give me a few real examples."
For public APIs: Research the API documentation using web search and subagents. Look for official docs, OpenAPI/Swagger specs, or developer portals.
For internal/private APIs: Ask the user: "How can I learn about this API?" (URL, spec file, or verbal description).
Determine the authentication method from API documentation during Phase 2 research. Do not ask the user about auth at this stage — discover it from the docs. Common patterns:
Credential values are collected later in Phase 6.2 — not during discovery.
MUST use ~/mcp-servers/<api-name>-mcp/ — this is the standard location for user-built MCP servers. Do not ask the user where to create it. Do not use any other path (not Chief-of-Staff/, not relative mcp-servers/, not temp directories). The auto-detect hook requires this exact location to show the MCPBuildCard contribution UI.
For external APIs: Use researcher subagent to find documentation. For internal APIs: Work from user-provided docs/descriptions.
See the relevant flow file for detailed instructions:
Synthesize findings into a working brief. In chat, keep it plain and explain what Rebel can do with the service; keep technical details in the working notes for the implementation handoff:
Based on use cases and research, propose 3-5 tools:
| Tool Name | User Task | What Rebel needs | What Rebel gives back |
|---|---|---|---|
search_customers | Find customers | query, limit | List of matches |
get_order | Check order status | order_id | Order details |
| ... | ... | ... | ... |
Present the tool list and ask:
Do not proceed until user approves the tool list.
For tool design best practices, load:
MANDATORY — Project path: All files related to this build — source code, tests, planning docs, research notes, scratch working files, conversation-specific notes — MUST live under
~/mcp-servers/<api-name>-mcp/(typicallysrc/for code,docs/for docs). Phase 4.2 below creates this directory and scaffolds the starter template — do not skip it. Do NOT write any build-related file toChief-of-Staff/, Private Space,memory/,Chief-of-Staff/temp/, temp directories, or relativemcp-servers/paths. Notes and research about the build belong beside the source code so they ship with any contribution PR. If you need a scratch file, create it under~/mcp-servers/<api-name>-mcp/docs/— never in Private Space. This overrides the generalChief-of-Staff/temp/rule for OSS MCP build work.
Mandatory workflow: Implementation must be orchestrated via the Software Engineer workflow. Do not implement the MCP inline from this skill. The Software Engineer workflow provides structured planning, staged implementation via subagents, and cross-family code review — ensuring higher quality output regardless of project complexity.
Assemble the following brief to hand off to the Software Engineer workflow:
Project setup:
~/mcp-servers/<api-name>-mcp/~/mcp-servers/<api-name>-mcp/docs/build-plan.md — this ships alongside the source code and is included in any contribution PRFrom earlier phases:
Required references (the planner and implementer must read these):
McpServer + registerTool() + Zod), naming conventions, error handling, module architecture, tool annotations, security baseline, packagingMandatory constraints:
McpServer + registerTool() + Zod schemas (not legacy server.tool())snake_case for all tool names and top-level parameter names.env file for credentials with .gitignore excluding .envreadOnlyHint, destructiveHint)URL and URLSearchParams for building query stringsDefinition of done:
npm run build succeeds without errorsYou MUST create the project directory and scaffold it from the starter template BEFORE delegating to the Software Engineer workflow. This ensures the directory exists at ~/mcp-servers/<api-name>-mcp/ so all subsequent file writes target the correct location.
Run these commands now:
mkdir -p ~/mcp-servers/<api-name>-mcp/src ~/mcp-servers/<api-name>-mcp/docs
Then read each starter template file and write its contents to the project directory. Do not guess or approximate the content — read the actual files from the starter template:
references/starter-template/package.json → Write to ~/mcp-servers/<api-name>-mcp/package.json. Change the name field to @mindstone/mcp-server-<api-name> (e.g. @mindstone/mcp-server-apple-shortcuts) — this is the public scoped name the package will be published under. Also update the description field to describe what the connector does. Using the scoped @mindstone/mcp-server-<api-name> prefix from the start means the PR reviewer sees the final published name, the catalog entry matches the npx specifier byte-for-byte, and the maintainer's publish workflow doesn't have to rename anything.references/starter-template/tsconfig.json → Write verbatim to ~/mcp-servers/<api-name>-mcp/tsconfig.jsonreferences/starter-template/.gitignore → Write verbatim to ~/mcp-servers/<api-name>-mcp/.gitignorereferences/starter-template/.env.example → Write verbatim to ~/mcp-servers/<api-name>-mcp/.env.examplereferences/starter-template/src/index.ts → Write to ~/mcp-servers/<api-name>-mcp/src/index.ts. Replace the PLACEHOLDER-mcp server handshake name with <api-name>-mcp (e.g. apple-shortcuts-mcp) so protocol logs match the package slug.references/starter-template/src/logger.ts → Write verbatim to ~/mcp-servers/<api-name>-mcp/src/logger.tsreferences/starter-template/LICENSE → Write verbatim to ~/mcp-servers/<api-name>-mcp/LICENSE. The default is FSL-1.1-MIT matching the upstream mindstone/mcp-servers repo — do not swap it unless the user is explicitly contributing elsewhere.references/starter-template/README.md → Write to ~/mcp-servers/<api-name>-mcp/README.md, then replace every <CONNECTOR_NAME>, <CONNECTOR_DESCRIPTION>, <AUTH_INSTRUCTIONS>, and <TOOL_LIST> placeholder with real content and remove the PRE_SUBMIT_PLACEHOLDER HTML-comment line at the top. The pre-submit gate in Phase 6.6 fails while that sentinel remains, which is intentional — it forces the README to be filled in before ready_to_submit.references/starter-template/test/smoke.test.mjs → Write verbatim to ~/mcp-servers/<api-name>-mcp/test/smoke.test.mjs. The scaffold smoke test validates an MCP handshake and tools/list against the built server using only Node.js built-ins (no extra dev-dependencies). The agent augments it with real tool-behaviour tests during Phase 6 — this file is a baseline, not the complete test suite.Do not skip this step. Do not delegate it to the Software Engineer workflow. The project must exist on disk before delegation.
Invoke the Software Engineer workflow with the brief above to perform the coding work. The project directory already exists at ~/mcp-servers/<api-name>-mcp/ with the starter template scaffolded.
The Software Engineer workflow will:
~/mcp-servers/<api-name>-mcp/docs/build-plan.mdWhen the Software Engineer workflow completes, resume here.
CHECKPOINT — Report draft status now:
rebel_mcp_report_contribution_state(
sessionId: <session_id from dynamic_env>,
connectorName: "<api-name>-mcp",
status: "draft",
localServerPath: "~/mcp-servers/<api-name>-mcp/"
)
This triggers the MCPBuildCard in the conversation UI. Do not skip this call.
Then continue with:
Before testing, run security checks on the generated code.
See script-security-review for the complete security checklist.
Key checks for MCP servers:
npm audit and fix Critical/High vulnerabilitiesIf this connector will be contributed to the mcp-servers repository, run the additional OSS security checks in contribute-connector.md § OSS Security Review. These cover internal reference stripping, bridge pattern removal, host-neutral error messages, and license/documentation requirements.
CHECKPOINT — Report testing status now:
rebel_mcp_report_contribution_state(
sessionId: <session_id from dynamic_env>,
connectorName: "<api-name>-mcp",
status: "testing"
)
Do not skip this call.
Testing reference: Load mcp-testing-guide.md for the recommended test strategy (mock API tests → mock client unit tests → declarative integration fallback), what to test (happy path, pagination, error handling, edge cases), debugging common failures (missing build artifacts, startup hangs, schema issues), and MCP Inspector usage.
Run the build commands in the project directory:
cd ~/mcp-servers/<api-name>-mcp/
npm install
npm run build
Never ask the user to paste an API key, token, or password into chat or a question card.
On desktop:
list_credentials. Use only the returned credential id; the secret value is never shown.list_credentials again to get its id..gitignore contains an exact .env entry:{
"command": "node -e \"const fs=require('fs'); const lines=fs.readFileSync('.gitignore','utf8').split(/\\r?\\n/); if(!lines.some(line=>line.trim()==='.env')) throw new Error('.gitignore must contain an exact .env entry before credentials are written')\""
}
.env from .env.example without overwriting an existing file. This is the cross-platform equivalent of cp -n .env.example .env:{
"command": "node -e \"const fs=require('fs'); if(!fs.existsSync('.env')) fs.copyFileSync('.env.example','.env')\""
}
credentials injection. The command refers only to process.env.PROVIDER_API_KEY; Rebel resolves the stored id directly into the child process environment, so the model never sees the value:{
"command": "node -e \"const fs=require('fs'); fs.appendFileSync('.env', 'PROVIDER_API_KEY=' + process.env.PROVIDER_API_KEY + '\\n', {mode: 0o600}); if(process.platform!=='win32') fs.chmodSync('.env',0o600)\"",
"credentials": [
{
"id": "<id from list_credentials>",
"envVar": "PROVIDER_API_KEY"
}
]
}
The .env intentionally stores the key as local plaintext so the sidecar can read it. The security improvement is that the model never sees the value and it never enters the conversation; .gitignore keeps the file out of version control.
On cloud or mobile, stored keys and Bash credential injection are desktop-only. Say so plainly and offer to continue this setup on desktop; do not fall back to collecting the key in chat.
Run the server to verify it starts without errors:
npm start
If startup fails, diagnose and fix the issue. For interactive tool testing, run MCP Inspector:
npx @modelcontextprotocol/inspector dist/index.js
Anti-pattern (don't do this). A common failure mode is to read the generic
rebel_mcp_add_servertool description, see permission framing there, and then pause to ask the user:// NEVER SAY THIS "Adding a connector is a protected admin action — may I proceed?"
That self-block is the exact regression this section is here to prevent. The generic tool description is written for sessions where there is no pre-arranged consent. You are in such a session right now: this skill IS the consent. The user invoked
build-custom-mcp-serverknowing it ends with registration; pausing to re-confirm wastes a turn and leaves them watching a half-finished build. If you find yourself drafting a permission question at this point, stop and register instead.Skill instructions take precedence over generic tool descriptions when the two appear to conflict. The tool description is the conservative default; the skill is the contract for this particular workflow.
MANDATORY — Register the server now, without asking. Call
rebel_mcp_add_serverdirectly. Do NOT useAskUserQuestionto check whether the user wants to register. The user invoked this skill; that is consent. The auto-detect hook needs this call to create the contribution record and show MCPBuildCard — skipping or gating it behind a question breaks the flow. Just register.
{
"name": "<api-name>",
"command": "node",
"args": ["~/mcp-servers/<api-name>-mcp/dist/index.js"],
"env": { /* credential env vars from .env */ }
}
See rebel-integration.md for detailed configuration options.
Call each tool via use_tool with realistic inputs — not just one representative tool. For every tool the connector exposes:
You will list every tool you tested, with inputs and results, in the <testing_evidence> block below before reporting ready_to_submit. Skipping tools here means emitting a dishonest evidence block — don't.
ready_to_submitTesting is your job before you tell Rebel the connector is ready. The user is trusting the connector to work against their real data. Treat the checklist below as a gate, not a suggestion.
Every item must be true. If any aren't, go fix it and re-run the affected steps.
npm run build succeeds with no errors.inputSchema.type === "object", every description non-empty.rebel_mcp_add_server called successfully and Rebel sees the tools (Phase 6.4).use_tool with realistic inputs — iterate per tool (Phase 6.5). Not one representative tool, not "they all look similar, I'll skip a few". Every single tool.<testing_evidence> block before reportingImmediately before calling rebel_mcp_report_contribution_state({status: "ready_to_submit", ...}), emit a visible <testing_evidence> block in the conversation listing every tool you tested, the input you used, what you expected, and what came back. One row per tool — no omissions. This is the proof that the checklist above is real, not aspirational.
Every row MUST include an http_status field (the HTTP status code observed by the tool handler, or N/A with a reason for tools that don't make HTTP calls). "PASS" requires HTTP 2xx (or the tool's documented success shape) — a row with http_status >= 400 or isError: true marked PASS is an explicit skill violation.
Format:
<testing_evidence>
tool: read_contact
input: { id: "contact-123" }
expected: returns Contact object with name and email
http_status: 200
actual: { id: "contact-123", name: "Ada Lovelace", email: "ada@example.com" } — PASS
tool: list_contacts
input: { limit: 5 }
expected: array of up to 5 Contact objects
http_status: 200
actual: [{...}, {...}] (2 items returned) — PASS
</testing_evidence>
If a tool failed, fix it — do not paper over it in the block. If a tool genuinely cannot be exercised without side effects on the user's account (e.g., a destructive delete_* tool), say so explicitly in the actual field, set http_status: N/A (destructive, not exercised), and note how you otherwise verified it (Inspector schema check, mocked unit test, etc.).
Credential-blocked rule: If you cannot obtain real credentials to exercise the tools, you MUST NOT report ready_to_submit. Stop at testing status and tell the user you are blocked on a credential — do not self-progress. Fabricated or all-isError: true evidence blocks are worse than none at all because they cause broken PRs to ship.
Phase 7 pre-flight (non-breaking gate): Before emitting the evidence block, run bash rebel-system/skills/coding/build-custom-mcp-server/scripts/pre-submit-check.sh . from the connector directory. It checks the Phase 7 quality items (LICENSE, README, tests directory, no dist committed, no internal references, npm audit clean) in one command. A non-zero exit must be resolved before ready_to_submit. This does not change when the state-machine checkpoint fires — it just gates the message you send immediately before it.
Environment-blocker handling (extends the credential-blocked rule above): If the script blocks on an environment issue you cannot fix on the user's behalf — ripgrep and grep both absent, npm install failing, npm audit unreachable because the machine is offline or behind a corporate registry — do not silently loop. Tell the user what the script is reporting, stay in testing status (do not fabricate a ready_to_submit report), and ask them to resolve the environment issue or authorise skipping the specific check. This is the same state-machine behaviour as the credential-blocked rule: additional blockers, same "stay in testing and be visible about it" response.
Only after the evidence block is emitted and pre-submit-check.sh exits clean do you call rebel_mcp_report_contribution_state with status: "ready_to_submit".
CHECKPOINT — Report ready_to_submit status with PR metadata now:
Before calling the checkpoint, prepare PR metadata:
Save the build plan to docs/build-plan.md in the connector directory. Copy the planning doc created by the Software Engineer workflow (from Phase 4) into the connector's docs/ directory so it ships with the PR. This gives reviewers full visibility into the research, implementation stages, and review history.
Compose the prTitle: Use feat: add <api-name> connector format.
Compose the prBody using the PR Description Template. Fill in every section from context captured during the build:
docs/build-plan.md.rebel_mcp_report_contribution_state(
sessionId: <session_id from dynamic_env>,
connectorName: "<api-name>-mcp",
status: "ready_to_submit",
localServerPath: "~/mcp-servers/<api-name>-mcp",
prTitle: "feat: add <api-name> connector",
prBody: "<composed PR body using the template above>"
)
IMPORTANT — supply localServerPath on the ready_to_submit call. The
contribution service treats the report as strict evidence that the connector
is working at a known path. Without localServerPath, the card stays in the
testing phase and the user sees a "Rebel got stuck checking this connector"
affordance. Pass the same path you wrote to disk — tilde paths like
~/mcp-servers/<api-name>-mcp are fine.
IMPORTANT — supply prTitle and prBody on the ready_to_submit call.
Without these, the in-app contribution flow falls back to a generic one-liner
PR description that gives reviewers no context about what problem is being
solved. The PR description is the primary artifact reviewers use to make merge
decisions — invest the effort to fill in the template properly.
If the tool call is rejected, read the error response and self-correct. A rejection response includes:
error — a short explanation (e.g. "Invalid transition: testing → draft.")currentStatus — what the record actually isattemptedStatus — what you tried to setRe-call rebel_mcp_report_contribution_state with a valid target status.
Never silently ignore a rejection — it means the card is stuck and the user
cannot progress.
nextAction grammar — read this when the tool returns isError: true.
When rebel_mcp_report_contribution_state returns a response body whose first line begins with Contribution state report deferred: or Contribution state report rejected:, the body contains a structured nextAction literal on the second line that tells you exactly what to do. Anchor on this textual signal — as of 2026-04-27, isError is propagated through the Super-MCP use_tool envelope, but this grammar remains the primary contract for resilience and auditability, so always read the response text. The values:
nextAction | When you'll see it | What to do |
|---|---|---|
run_tests | You reported ready_to_submit without test evidence in this session. | Run Bash tests, then call every exposed tool via use_tool with real inputs. If Rebel shows zero tools, or any tool still fails, fix that first — do not invent tool calls or emit a placeholder <testing_evidence> block. Only after the real tool calls succeed do you emit <testing_evidence> and re-call rebel_mcp_report_contribution_state(status: "ready_to_submit", localServerPath: "~/mcp-servers/<api-name>-mcp/", ...). |
register_server | You reported ready_to_submit without registering the connector via rebel_mcp_add_server. | Call rebel_mcp_add_server exactly as in Phase 6.4 (see the anti-pattern callout there: skill invocation is consent — do NOT pause to ask permission), using the built server under ~/mcp-servers/<api-name>-mcp/. If rebel_mcp_add_server returns an error, fix that error and retry the add-server call first. Only re-call rebel_mcp_report_contribution_state(status: "ready_to_submit", ...) after rebel_mcp_add_server succeeds. |
move_to_canonical_path | Your connector lives outside ~/mcp-servers/<api-name>-mcp/. | Move all source files to ~/mcp-servers/<api-name>-mcp/, re-register via rebel_mcp_add_server against the new path, then re-call with localServerPath: "~/mcp-servers/<api-name>-mcp/". |
reauth_github | The user's GitHub token has been revoked or the grant is gone. | Tell the user: "Please reconnect GitHub in Settings → Connectors so we can send it out." Then stop. Do not re-call rebel_mcp_report_contribution_state, do not try to open an auth flow yourself, and do not mark the contribution complete. Only the user can resolve this. |
wait_for_review | The status you tried to set is not a valid next transition from the current state. | Read the current_status=... parenthetical and the guidance line — they tell you the actual current state and the valid next states. Either re-call once with one of those valid statuses, copied verbatim, or stop reporting. Do not re-send the same invalid status, and do not guess a different status that is not listed. |
run_software_engineer_workflow | You reported ready_to_submit on a non-trivial connector without invoking the Software Engineer workflow. | Read rebel-system/skills/workflows/software-engineer/SKILL.md, then re-run the build phases as the SE planner/implementer/reviewer. Re-call rebel_mcp_report_contribution_state(status: "ready_to_submit", ...) once docs/build-plan.md reflects the SE working-doc template (workflow: software-engineer, models.*, ## Review History). |
run_software_engineer_workflow | You ran the Software Engineer workflow earlier, but the connector code has changed since. The SE evidence on this contribution was invalidated and must be refreshed against the current build state. | Re-invoke the Software Engineer workflow against the current connector path. The SE working doc at docs/build-plan.md should be updated (or re-created) to reflect the changed code. Re-call rebel_mcp_report_contribution_state(status: "ready_to_submit", ...) once SE has run on the new build state. |
Never ignore a Contribution state report deferred: or Contribution state report rejected: response body. Reading the response, picking the right nextAction, and re-calling within the same conversation turn is the only way to keep the contribution flow moving. Silent acceptance of a deferred state means the build card stays stuck and the user can't ship.
Always act on the latest rebel_mcp_report_contribution_state result only. Older deferred/rejected results in the conversation may already be superseded by a later call.
Do not skip this call.
Before moving to community submission, review this checklist. Each item represents a quality standard that ensures the server is production-ready and maintainable. Community submission happens in Phase 8 after these checks pass.
.env for credentials, .gitignore excludes .envsnake_case with a service prefix (e.g., zendesk_search_tickets)snake_caselimit, page_token/cursor, return_json, {thing}_idreadOnlyHint and destructiveHint annotations set correctlyreadOnlyHint: true, destructiveHint: falsereadOnlyHint: false, destructiveHint: falsereadOnlyHint: false, destructiveHint: true.env.example documents all required environment variablesnpm run build succeeds without errorsbin field in package.json points to dist/index.js (for npx distribution)files: ["dist"] in package.json to limit package contents#!/usr/bin/env node) at the top of the entry filepackage.json has a "license" field (e.g. "FSL-1.1-MIT") matching the LICENSE fileserver.json registry manifest present alongside package.json. Inherited from connectors/_template/server.json when scaffolding from the template. Replace every CONNECTOR_NAME / CONNECTOR_TITLE / CONNECTOR_DESCRIPTION placeholder, declare every required+optional env var (exclude bridge-only env vars MCP_HOST_BRIDGE_STATE / MINDSTONE_REBEL_BRIDGE_STATE), and validate locally with mcp-publisher validate server.json. The CI workflow .github/workflows/server-json-check.yml runs the same check on every PR. Schema reference: contribute-connector.md § MCP Registry Submission.mcpName field in package.json equals server.json.name exactly (io.github.mindstone/mcp-server-<connector>). The registry uses it to verify namespace ownership.Real PRs produced by this skill have been blocked on the following items. pre-submit-check.sh catches most of them automatically; the rest are your responsibility to verify before reporting ready_to_submit.
dist/ — always listed in .gitignore; never git add the build output. The submit-pr-to-rebel-oss files list must not include dist/**."license" field in package.json — the LICENSE file alone is insufficient. Add "license": "FSL-1.1-MIT" (or whichever license matches the upstream repo).~/mcp-servers/<name>-mcp or /Users/<name>/... in setup instructions. Use <absolute path to>/mcp-servers/<name>/dist/index.js or similar neutral placeholder.destructiveHint: false on tools that run external shell/AppleScript/binary commands — any tool that invokes a subprocess or triggers a user-visible side effect on the host must set destructiveHint: true, regardless of what the underlying binary "usually" does.--input-path / --input-file flag expects a filesystem path, not raw text; if you want to feed text to a subprocess, write it to a temp file first or use stdin.spawn()/exec() without a timeout — always set an explicit timeout option. A stalled child hangs the MCP server and every tool call behind it.src/ so schema drift breaks the tests. z.object({...}) recreated inside a test file means the test is validating a parallel copy that will silently diverge.Include this phase explicitly in any task list or plan you create. The build is not complete when
ready_to_submitis reported — it is complete when the user has submitted (or declined to submit) the connector to the community. Treat this as a named, tracked step of the plan, not a conversational afterthought.
After Phase 7's quality checklist passes (ready_to_submit was reported at the end of Phase 6), guide the user through the community submission step. Other Rebel users can install submitted connectors with one click, so this is the point of the whole build flow for most users.
Build Context appendix — auto-injected, do not compose manually
The Build Context block (model, app-version, session-id, task-subagent observations, build-plan shape) is auto-injected into your PR body. You do NOT need to compose it manually. If you write your own prBody override, the Build Context block is still appended after your content — your override sits above it.
Primary path — in-app contribution flow:
Use the in-app "Add to the community" flow (the rebel_mcp_report_contribution_state tool is always available as a bundled tool):
rebel_mcp_report_contribution_state was already called with status ready_to_submit at the end of Phase 6. If not, call it now.The in-app flow uses the contribution service (IPC channels:
contribution:start-auth,contribution:submit) to automate the entire GitHub workflow. The user just clicks a button.
If the user declines to submit (wants to keep the connector private), acknowledge that and stop — do not press. The connector is still usable locally; the community submission is optional from the user's perspective even though it is a mandatory plan step from yours.
Fallback — manual Git workflow:
If the in-app tools aren't available, or the user explicitly prefers manual control, delegate the PR mechanics to the submit-pr-to-rebel-oss skill. That skill owns the generic fork/branch/commit/push/PR flow via the GitHub Git Data API; this skill stays responsible for the MCP-specific context (PR template, file list, OSS security review).
STOP before invoking the PR skill — all of these must be true:
- Phase 7 quality review and the OSS Security Review have passed. The PR skill refuses to run without this, but the responsibility to confirm lives here.
prTitleandprBodyare composed using the PR Description Template. A generic one-liner body is rejected.filesenumerates every connector file — see the list below. Nogit add ., no wildcards.- No
dist/,node_modules/,.env(actual credentials), coverage output, or IDE config is infiles.
Pass the following parameters to the submit-pr-to-rebel-oss skill:
| Param | Value for a new MCP connector PR |
|---|---|
repo | mindstone/mcp-servers |
baseBranch | main |
branchName | feat/<api-name>-connector (e.g. feat/zendesk-connector) |
commitMessage | feat(<api-name>): add <api-name> connector |
prTitle | feat: add <api-name> connector (matches the title you reported via rebel_mcp_report_contribution_state) |
prBody | The markdown you composed from the PR Description Template |
pathAllowlistPrefix | connectors/<api-name>/ |
files | The full source→destination list below |
files — every file is an object with a source (your local build directory) and destination (where it lands in mcp-servers). The directories differ because the connector is built off-repo. The example below uses JSON with comments (jsonc) for readability — strip the comments before passing the array to the skill:
[
{ "source": "~/mcp-servers/<api-name>-mcp/package.json", "destination": "connectors/<api-name>/package.json" },
{ "source": "~/mcp-servers/<api-name>-mcp/tsconfig.json", "destination": "connectors/<api-name>/tsconfig.json" },
{ "source": "~/mcp-servers/<api-name>-mcp/.gitignore", "destination": "connectors/<api-name>/.gitignore" },
{ "source": "~/mcp-servers/<api-name>-mcp/.env.example", "destination": "connectors/<api-name>/.env.example" },
{ "source": "~/mcp-servers/<api-name>-mcp/LICENSE", "destination": "connectors/<api-name>/LICENSE" },
{ "source": "~/mcp-servers/<api-name>-mcp/README.md", "destination": "connectors/<api-name>/README.md" },
{ "source": "~/mcp-servers/<api-name>-mcp/src/index.ts", "destination": "connectors/<api-name>/src/index.ts" },
{ "source": "~/mcp-servers/<api-name>-mcp/src/logger.ts", "destination": "connectors/<api-name>/src/logger.ts" },
// ...every additional source file under src/
{ "source": "~/mcp-servers/<api-name>-mcp/test/smoke.test.mjs", "destination": "connectors/<api-name>/test/smoke.test.mjs" },
// ...every additional test file under test/
{ "source": "~/mcp-servers/<api-name>-mcp/docs/build-plan.md", "destination": "connectors/<api-name>/docs/build-plan.md" }
]
Include every file under your build directory that belongs in the PR. Exclude node_modules/, dist/, .env with real credentials, coverage output, and IDE config. The docs/build-plan.md Software Engineer working document ships with the PR — it gives reviewers the full research, implementation, and review history.
When the submit-pr-to-rebel-oss skill returns, report the PR number and URL to the user.
Phase 4 implementation is always orchestrated through the Software Engineer workflow. Project complexity affects how many implementation stages the planner creates and how detailed the working document needs to be — not whether the workflow is used. Even a simple 3-tool MCP benefits from structured planning and cross-family code review.
references/ docs, don't reinvent MCP best practicesUser needs to install Node.js: https://nodejs.org
Run npm install in the project folder
User needs to create .env file with credentials