write-rfc

# Write RFC Skill This skill helps you write high-quality RFCs for the ToolHive ecosystem following established patterns and conventions. ## Overview ToolHive RFCs follow a specific format with the naming convention `THV-{NUMBER}-{descriptive-name}.md`. The NUMBER must match the PR number and be zero-padded to 4 digits. ## Workflow ### Step 1: Gather Requirements Before writing an RFC, ask the user about: 1. **Problem Statement**: What problem are they trying to solve? 2. **Target Repository**: Which repo does this affect? - `toolhive` - Core runtime, CLI (`thv`), operator (`thv-operator`), proxy-runner (`thv-proxyrunner`), virtual MCP (`vmcp`) - `toolhive-studio` - Desktop UI application (Electron/TypeScript) - `toolhive-registry` - MCP server registry data - `toolhive-registry-server` - Registry API server (`thv-registry-api`) - `toolhive-cloud-ui` - Cloud/Enterprise web UI (Next.js) - `dockyard` - Container packaging for MCP servers - `multiple` - Cross-cutting changes 3. **Scope**: What are the goals and explicit non-goals? ### Step 2: Research the Ecosystem Before drafting, research the relevant codebase: #### 2.1 Fetch Architectural Documentation Use `mcp__github__get_file_contents` to read from `stacklok/toolhive` repo's `docs/arch/` directory: | Document | Content | |----------|---------| | `00-overview.md` | Platform overview, key components | | `01-deployment-modes.md` | Local vs Kubernetes modes | | `02-core-concepts.md` | Nouns (Workloads, Transports, Proxy, etc.) and Verbs | | `03-transport-architecture.md` | stdio, SSE, streamable-http transports | | `04-secrets-management.md` | Secrets handling, providers | | `05-runconfig-and-permissions.md` | Configuration format, permission profiles | | `06-registry-system.md` | Registry architecture, MCPRegistry CRD | | `07-groups.md` | Server grouping concepts | | `08-workloads-lifecycle.md` | Lifecycle management | | `09-operator-architecture.md` | K8s operator, CRDs | | `10-virtual-mcp-architecture.md` | Virtual MCP aggregation | #### 2.2 Review Existing RFCs Read `rfcs/` directory in this repository to understand patterns and check for related proposals. #### 2.3 Search Relevant Codebases Use `mcp__github__search_code` or `mcp__github__get_file_contents` to explore: | Repository | Purpose | |------------|---------| | `stacklok/toolhive` | Core platform, CLI, operator, proxy | | `stacklok/toolhive-studio` | Desktop UI | | `stacklok/toolhive-registry-server` | Registry API server | | `stacklok/toolhive-registry` | Registry data | | `stacklok/toolhive-cloud-ui` | Cloud/Enterprise UI | | `stacklok/dockyard` | Container packaging | ### Step 3: Draft the RFC Create the RFC following the template structure from `rfcs/0000-template.md`. #### Required Metadata ```markdown # RFC-XXXX: Title - **Status**: Draft - **Author(s)**: Name (@github-handle) - **Created**: YYYY-MM-DD - **Last Updated**: YYYY-MM-DD - **Target Repository**: [from step 1] - **Related Issues**: [links if applicable] ``` #### Core Sections 1. **Summary** - 2-3 sentences capturing the essence 2. **Problem Statement** - Current limitation, who's affected, why it matters 3. **Goals** - Specific objectives (bulleted) 4. **Non-Goals** - Explicit scope boundaries 5. **Proposed Solution** - High-Level Design (with Mermaid diagrams) - Detailed Design: Component changes, API changes, configuration changes, data model changes 6. **Security Considerations** (REQUIRED) - See security checklist below 7. **Alternatives Considered** - Other approaches evaluated 8. **Compatibility** - Backward and forward compatibility 9. **Implementation Plan** - Phased approach with tasks 10. **Testing Strategy** - Unit, integration, E2E, performance, security tests 11. **Documentation** - What needs documenting 12. **Open Questions** - Unresolved items 13. **References** - Related links #### Security Considerations Checklist (REQUIRED) Every RFC MUST address: - [ ] **Threat Model** - Potential threats, attacker capabilities - [ ] **Authentication and Authorization** - Auth changes, permission models - [ ] **Data Security** - Sensitive data handling, encryption - [ ] **Input Validation** - User input, injection vectors - [ ] **Secrets Management** - Credentials storage, rotation - [ ] **Audit and Logging** - Security events, compliance - [ ] **Mitigations** - Security controls implemented ### Step 4: Use Proper Conventions #### Code Examples - Use **Go** for API changes in toolhive, toolhive-registry-server - Use **TypeScript** for toolhive-studio, toolhive-cloud-ui changes - Use **YAML** for configuration examples - Use **Mermaid** for diagrams (flowcharts, sequence diagrams) #### Kubernetes CRDs If the RFC involves Kubernetes, include CRD examples: ```yaml apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: name: example spec: # ... ``` CRD types: `MCPServer`, `MCPRegistry`, `MCPToolConfig`, `MCPExternalAuthConfig`, `MCPGroup`, `VirtualMCPServer` ### Step 5: File Naming The RFC file should be named `THV-XXXX-{descriptive-name}.md` where XXXX is the PR number. Since you don't know the PR number yet, use a placeholder like `THV-XXXX-{name}.md` and remind the user to rename it to match the PR number after creating the PR. ### Step 6: Review Checklist Before finalizing, verify: - [ ] Problem is clearly stated - [ ] Goals and non-goals are explicit - [ ] Security section is complete (all 7 areas addressed) - [ ] Alternatives are discussed - [ ] Diagrams illustrate complex flows - [ ] Code examples are concrete and in the correct language - [ ] Implementation phases are defined - [ ] Testing strategy covers all levels - [ ] File follows naming convention ## ToolHive Architecture Summary ### Platform Overview ToolHive is a **platform** for MCP server management (not just a container runner): - **Proxy layer** with middleware (auth, authz, audit, rate limiting) - **Security** by default (network isolation, permission profiles) - **Aggregation** via Virtual MCP Server - **Registry** for curated MCP servers - **Multi-deployment**: Local (CLI/UI) and Kubernetes (operator) ### Key Binaries | Binary | Location | Purpose | |--------|----------|---------| | `thv` | toolhive | Main CLI | | `thv-operator` | toolhive | Kubernetes operator | | `thv-proxyrunner` | toolhive | K8s proxy container | | `vmcp` | toolhive | Virtual MCP server (aggregation) | | `thv-registry-api` | toolhive-registry-server | Registry API server | ### Transport Types - **stdio** - Standard input/output (requires protocol translation) - **SSE** - Server-Sent Events (HTTP, transparent proxy) - **streamable-http** - HTTP streaming (transparent proxy) ### Design Principles 1. Platform abstraction over direct execution 2. Security by default (network isolation, permissions) 3. Extensibility through middleware 4. Cloud-native (K8s operators, containers) 5. RunConfig as portable API contract ## Reference Files - Template: `rfcs/0000-template.md` - Contributing guide: `CONTRIBUTING.md` - Existing RFCs: `rfcs/THV-*.md`