build-custom-mcp-server

Files (27)

• LICENSE.txt
• SKILL.md
• contribute-connector.md · references/
• evaluation.md · references/
• flow-external-api.md · references/
• flow-internal-api.md · references/
• mcp-development-standard.md · references/
• mcp-testing-guide.md · references/
• mcp_best_practices.md · references/
• node_mcp_server.md · references/
• python_mcp_server.md · references/
• rebel-integration.md · references/
• .env.example · references/starter-template/
• .gitignore · references/starter-template/
• LICENSE · references/starter-template/
• README.md · references/starter-template/
• package.json · references/starter-template/
• index.ts · references/starter-template/src/
• logger.ts · references/starter-template/src/
• smoke.test.mjs · references/starter-template/test/
• tsconfig.json · references/starter-template/
• timezone_handling.md · references/
• connections.py · scripts/
• evaluation.py · scripts/
• example_evaluation.xml · scripts/
• pre-submit-check.sh · scripts/
• requirements.txt · scripts/

SKILL.md (first lines)

# Create MCP Server

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.

## Voice Firewall — How to Talk to Non-Technical Users

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:**

- Default to "we" during build and testing.
- Use "you" for ownership and decisions: attribution, sharing, keeping private, withdrawing.

**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_best_practices.md](references/mcp_best_practices.md) - Universal MCP design guidelines
- [node_mcp_server.md](references/node_mcp_server.md) - TypeScript implementation patterns
- [python_mcp_server.md](references/python_mcp_server.md) - Python/FastMCP patterns
- [evaluation.md](references/evaluation.md) - Creating evaluation harnesses
- [mcp-development-standard.md](references/mcp-development-standard.md) - SDK patterns, naming conventions, error handling, module architecture, security baseline, packaging
- [mcp-testing-guide.md](references/mcp-testing-guide.md) - Test strategy, test patterns, debugging common failures
- [contribute-connector.md](references/contribute-connector.md) - Contributing your MCP back to the ecosystem (lifecycle, PR template, quality bar, CI pipeline)

## Key Principles

1. **User's existing codebase is READ-ONLY** - analyze to understand API, never modify
2. **MCP project is created separately** - at `~/mcp-servers/<api-name>-mcp/`
3. **Rebel creates files for the user** - don't just provide snippets to copy
4. **Start small** - 3-5 tools for first iteration (though more tools are fine—Rebel's Super-MCP uses progressive discovery so tool count isn't a hard constraint)
5. **Use subagents for research** - delegate API doc discovery to researcher

## Agent-Centric Design Principles

Before implementation, understand how to design tools for AI agents:

**Build for Workflows, Not Just API Endpoints:**

- Don't simply wrap existing API endpoints - build thoughtful workflow tools
- Consolidate related operations (e.g., `schedule_event` that checks availability AND creates event)
- Focus on tools that enable complete tasks, not just individual API calls

**Optimize for Limited Context:**

- Agents have constrained context windows - make every token count
- Return high-signal information, not exhaustive data dumps
- Provide "concise" vs "detailed" response format options
- Default to human-readable identifiers over technical codes (names over IDs)

**Design Actionable Error Messages:**

- Error messages should guide agents toward correct usage
- Suggest specific next steps: "Try using filter='active_only' to reduce results"
- Help agents learn proper tool usage through clear feedback

**Use Evaluation-Driven Development:**

- Create realistic evaluation scenarios early (see [evaluation.md](references/evaluation.md))
- Let agent feedback drive tool improvements
- Prototype quickly and iterate based on actual agent performance

## Contribution Lifecycle

// internal — do not narrate to user

> **MANDATORY — You MUST call `rebel_mcp_report_contribution_state` after building the connector.** This is not optional. The moment you finish writing the connector code (all source files created, build succeeds), call this tool with `status: "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](references/contribute-connector.md#pr-description-template). **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 |

From mindstone/rebel-system, MIT.

More from mindstone/rebel-system