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

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

stacklok/toolhive

docs/arch/

00-overview.md

01-deployment-modes.md

02-core-concepts.md

03-transport-architecture.md

04-secrets-management.md

05-runconfig-and-permissions.md

06-registry-system.md

07-groups.md

08-workloads-lifecycle.md

09-operator-architecture.md

10-virtual-mcp-architecture.md

2.2 Review Existing RFCs

Read

rfcs/

2.3 Search Relevant Codebases

Use

mcp__github__search_code

mcp__github__get_file_contents

stacklok/toolhive

stacklok/toolhive-studio

stacklok/toolhive-registry-server

stacklok/toolhive-registry

stacklok/toolhive-cloud-ui

stacklok/dockyard

Step 3: Draft the RFC

Create the RFC following the template structure from

rfcs/0000-template.md

Required Metadata

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

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

THV-XXXX-{name}.md

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

thv

thv-operator

thv-proxyrunner

vmcp

thv-registry-api

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