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:

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:

Step 3: Draft the RFC

Create the RFC following the template structure from rfcs/0000-template.md.

Required Metadata

markdown
1# RFC-XXXX: Title
2
3- **Status**: Draft
4- **Author(s)**: Name (@github-handle)
5- **Created**: YYYY-MM-DD
6- **Last Updated**: YYYY-MM-DD
7- **Target Repository**: [from step 1]
8- **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
1apiVersion: toolhive.stacklok.dev/v1alpha1
2kind: MCPServer
3metadata:
4  name: example
5spec:
6  # ...

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

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