From fd5cb32bae84ca490d831ac2dfe9ac01cd94cb02 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 6 Oct 2026 14:58:40 +0300 Subject: [PATCH 1/4] Reorganize repo into per-project folders Move ToolHive RFCs to toolhive/, the shared template to template.md, add a per-project README, and make the naming workflow resolve the filename prefix from the project folder. Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Radoslav Dimitrov --- .../workflows/validate-proposal-naming.yml | 37 ++++++++++++++----- CONTRIBUTING.md | 17 +++++---- README.md | 35 +++++++++--------- SECURITY.md | 2 +- rfcs/0000-template.md => template.md | 2 +- toolhive/README.md | 17 +++++++++ .../THV-0001-otel-integration-proposal.md | 0 ...ive-kubernetes-architecture-improvement.md | 0 ...04-upstream-mcp-registry-format-support.md | 0 ...5-environment-variable-secrets-fallback.md | 0 .../THV-0006-groups-in-registry.md | 0 .../THV-0007-token-exchange-middleware.md | 0 .../THV-0008-virtual-mcp-server.md | 0 .../THV-0009-remote-mcp-proxy.md | 0 .../THV-0010-kubernetes-mcpgroup-crd.md | 0 ...HV-0011-refactor-mcpregistry-controller.md | 0 .../THV-0012-custom-package-registries.md | 0 ...HV-0013-kubernetes-registry-source-type.md | 0 .../THV-0014-vmcp-k8s-aware-refactor.md | 0 .../THV-0015-tool-definitions-extension.md | 0 .../THV-0017-dynamic-webhook-middleware.md | 0 .../THV-0019-auth-server-design.md | 0 .../THV-0019-auth-server-overview.md | 0 .../THV-0020-desktop-cli-version-alignment.md | 0 {rfcs => toolhive}/THV-0021-thvignore.md | 0 .../THV-0022-optimizer-migration-to-vmcp.md | 0 .../THV-0023-crd-v1beta1-optimization.md | 0 .../THV-0026-header-passthrough.md | 0 ...THV-0029-skills-support-registry-server.md | 0 .../THV-0030-skills-lifecycle-management.md | 0 .../THV-0031-auth-server-integration.md | 0 .../THV-0032-toolhive-core-shared-library.md | 0 .../THV-0033-aws-sts-agent-delegation.md | 0 .../THV-0034-long-running-local-server.md | 0 .../THV-0035-auth-server-redis-storage.md | 0 ...HV-0038-session-scoped-client-lifecycle.md | 0 .../THV-0041-sqlite-state-management.md | 0 .../THV-0043-registry-authentication.md | 0 ...047-vmcp-proxyrunner-horizontal-scaling.md | 0 .../THV-0050-embedded-as-with-aws-sts.md | 0 .../THV-0052-multi-upstream-idp-authserver.md | 0 .../THV-0053-vmcp-embedded-authserver.md | 0 .../THV-0054-vmcp-upstream-inject-strategy.md | 0 ...5-mcpserverentry-direct-remote-backends.md | 0 .../THV-0056-scoped-secret-store.md | 0 {rfcs => toolhive}/THV-0057-rate-limiting.md | 0 .../THV-0059-vmcp-local-experience.md | 0 .../THV-0068-workload-upgrade.md | 0 .../THV-0070-thv-llm-subcommand.md | 0 {rfcs => toolhive}/THV-0071-cimd-support.md | 0 ...V-0072-vmcp-multi-upstream-partial-auth.md | 0 .../THV-0073-vmcp-session-identity-binding.md | 0 .../THV-0076-vmcp-core-interface.md | 0 .../THV-0077-plugins-lifecycle-management.md | 0 .../THV-0078-decouple-vmcp-config-from-crd.md | 0 .../THV-0079-cross-app-access-grant.md | 0 .../THV-0080-skills-lock-file.md | 0 .../THV-0081-stateless-transport-proxies.md | 0 {rfcs => toolhive}/THV-0083-stateless-vmcp.md | 0 59 files changed, 73 insertions(+), 37 deletions(-) rename rfcs/0000-template.md => template.md (97%) create mode 100644 toolhive/README.md rename {rfcs => toolhive}/THV-0001-otel-integration-proposal.md (100%) rename {rfcs => toolhive}/THV-0003-toolhive-kubernetes-architecture-improvement.md (100%) rename {rfcs => toolhive}/THV-0004-upstream-mcp-registry-format-support.md (100%) rename {rfcs => toolhive}/THV-0005-environment-variable-secrets-fallback.md (100%) rename {rfcs => toolhive}/THV-0006-groups-in-registry.md (100%) rename {rfcs => toolhive}/THV-0007-token-exchange-middleware.md (100%) rename {rfcs => toolhive}/THV-0008-virtual-mcp-server.md (100%) rename {rfcs => toolhive}/THV-0009-remote-mcp-proxy.md (100%) rename {rfcs => toolhive}/THV-0010-kubernetes-mcpgroup-crd.md (100%) rename {rfcs => toolhive}/THV-0011-refactor-mcpregistry-controller.md (100%) rename {rfcs => toolhive}/THV-0012-custom-package-registries.md (100%) rename {rfcs => toolhive}/THV-0013-kubernetes-registry-source-type.md (100%) rename {rfcs => toolhive}/THV-0014-vmcp-k8s-aware-refactor.md (100%) rename {rfcs => toolhive}/THV-0015-tool-definitions-extension.md (100%) rename {rfcs => toolhive}/THV-0017-dynamic-webhook-middleware.md (100%) rename {rfcs => toolhive}/THV-0019-auth-server-design.md (100%) rename {rfcs => toolhive}/THV-0019-auth-server-overview.md (100%) rename {rfcs => toolhive}/THV-0020-desktop-cli-version-alignment.md (100%) rename {rfcs => toolhive}/THV-0021-thvignore.md (100%) rename {rfcs => toolhive}/THV-0022-optimizer-migration-to-vmcp.md (100%) rename {rfcs => toolhive}/THV-0023-crd-v1beta1-optimization.md (100%) rename {rfcs => toolhive}/THV-0026-header-passthrough.md (100%) rename {rfcs => toolhive}/THV-0029-skills-support-registry-server.md (100%) rename {rfcs => toolhive}/THV-0030-skills-lifecycle-management.md (100%) rename {rfcs => toolhive}/THV-0031-auth-server-integration.md (100%) rename {rfcs => toolhive}/THV-0032-toolhive-core-shared-library.md (100%) rename {rfcs => toolhive}/THV-0033-aws-sts-agent-delegation.md (100%) rename {rfcs => toolhive}/THV-0034-long-running-local-server.md (100%) rename {rfcs => toolhive}/THV-0035-auth-server-redis-storage.md (100%) rename {rfcs => toolhive}/THV-0038-session-scoped-client-lifecycle.md (100%) rename {rfcs => toolhive}/THV-0041-sqlite-state-management.md (100%) rename {rfcs => toolhive}/THV-0043-registry-authentication.md (100%) rename {rfcs => toolhive}/THV-0047-vmcp-proxyrunner-horizontal-scaling.md (100%) rename {rfcs => toolhive}/THV-0050-embedded-as-with-aws-sts.md (100%) rename {rfcs => toolhive}/THV-0052-multi-upstream-idp-authserver.md (100%) rename {rfcs => toolhive}/THV-0053-vmcp-embedded-authserver.md (100%) rename {rfcs => toolhive}/THV-0054-vmcp-upstream-inject-strategy.md (100%) rename {rfcs => toolhive}/THV-0055-mcpserverentry-direct-remote-backends.md (100%) rename {rfcs => toolhive}/THV-0056-scoped-secret-store.md (100%) rename {rfcs => toolhive}/THV-0057-rate-limiting.md (100%) rename {rfcs => toolhive}/THV-0059-vmcp-local-experience.md (100%) rename {rfcs => toolhive}/THV-0068-workload-upgrade.md (100%) rename {rfcs => toolhive}/THV-0070-thv-llm-subcommand.md (100%) rename {rfcs => toolhive}/THV-0071-cimd-support.md (100%) rename {rfcs => toolhive}/THV-0072-vmcp-multi-upstream-partial-auth.md (100%) rename {rfcs => toolhive}/THV-0073-vmcp-session-identity-binding.md (100%) rename {rfcs => toolhive}/THV-0076-vmcp-core-interface.md (100%) rename {rfcs => toolhive}/THV-0077-plugins-lifecycle-management.md (100%) rename {rfcs => toolhive}/THV-0078-decouple-vmcp-config-from-crd.md (100%) rename {rfcs => toolhive}/THV-0079-cross-app-access-grant.md (100%) rename {rfcs => toolhive}/THV-0080-skills-lock-file.md (100%) rename {rfcs => toolhive}/THV-0081-stateless-transport-proxies.md (100%) rename {rfcs => toolhive}/THV-0083-stateless-vmcp.md (100%) diff --git a/.github/workflows/validate-proposal-naming.yml b/.github/workflows/validate-proposal-naming.yml index 0a8f047..0f04d98 100644 --- a/.github/workflows/validate-proposal-naming.yml +++ b/.github/workflows/validate-proposal-naming.yml @@ -5,7 +5,7 @@ permissions: on: pull_request: paths: - - 'rfcs/**' + - '*/**' types: [opened, synchronize] workflow_dispatch: inputs: @@ -37,8 +37,14 @@ jobs: - name: Validate proposal naming run: | - # Get the list of NEW files added in rfcs/ (not modifications to existing files) - CHANGED_FILES=$(git diff --name-only --diff-filter=A origin/${{ github.base_ref }}...HEAD | grep '^rfcs/' || true) + # Map of project folder -> RFC filename prefix. Add a line here when onboarding a new project. + declare -A PREFIXES=( + [toolhive]="THV" + ) + + # Get the list of NEW files added in a project folder (not modifications to existing files). + # Only top-level project folders are considered; READMEs are not RFCs. + CHANGED_FILES=$(git diff --name-only --diff-filter=A origin/${{ github.base_ref }}...HEAD | grep -E '^[^./][^/]*/[^/]+\.md$' | grep -vE '/README\.md$' || true) # Skip validation if no new proposal files are being added # (modifications to existing proposals don't need naming validation) @@ -57,14 +63,24 @@ jobs: while IFS= read -r file; do if [ -n "$file" ] && [ -f "$file" ]; then filename=$(basename "$file") - echo "Checking file: $filename" + project=$(dirname "$file") + echo "Checking file: $file" + + prefix="${PREFIXES[$project]:-}" + if [ -z "$prefix" ]; then + echo "❌ '$project' is not a registered project folder" + echo " Registered projects: ${!PREFIXES[*]}" + echo " Add it to the PREFIXES map in this workflow." + VALIDATION_FAILED=true + continue + fi - # Check if the filename follows the THV-####-name pattern with the current PR number - if echo "$filename" | grep -qE "^THV-${PR_NUMBER}-.*\.md$"; then + # Check if the filename follows the -####-name pattern with the current PR number + if echo "$filename" | grep -qE "^${prefix}-${PR_NUMBER}-.*\.md$"; then echo "✅ $filename follows the correct naming convention" else echo "❌ $filename does not follow the correct naming convention" - echo " Expected format: THV-${PR_NUMBER}-name-of-your-proposal.md" + echo " Expected format: ${project}/${prefix}-${PR_NUMBER}-name-of-your-proposal.md" echo " Where ${PR_NUMBER} is the current PR number" VALIDATION_FAILED=true fi @@ -77,16 +93,17 @@ jobs: echo "❌ Validation failed! Some proposal files do not follow the naming convention." echo "" echo "Proposal files must follow this naming pattern:" - echo " THV-${PR_NUMBER}-name-of-your-proposal.md" + echo " /-${PR_NUMBER}-name-of-your-proposal.md" echo "" echo "Where:" - echo " - THV- is the prefix" + echo " - is the project folder (e.g. toolhive)" + echo " - - is that project's prefix (e.g. THV-)" echo " - ${PR_NUMBER} is the current PR number" echo " - name-of-your-proposal is a descriptive name in kebab-case" echo " - .md is the file extension" echo "" echo "Example of valid name for this PR:" - echo " - THV-${PR_NUMBER}-new-feature-proposal.md" + echo " - toolhive/THV-${PR_NUMBER}-new-feature-proposal.md" echo "" exit 1 else diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11cdb1e..ae58f90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to ToolHive RFCs +# Contributing to Stacklok RFCs First off, thank you for taking the time to contribute to ToolHive! :+1: :tada: ToolHive is released under the Apache 2.0 license. If you would like to @@ -57,7 +57,7 @@ If you're new to the RFC process: 1. Read through existing RFCs to understand the format and level of detail expected 2. Start with a thread on [Discord](https://discord.gg/stacklok) to validate your idea -3. Review the [RFC template](rfcs/0000-template.md) to understand what sections are required +3. Review the [RFC template](template.md) to understand what sections are required ### RFC submission process @@ -66,7 +66,8 @@ If you're new to the RFC process: 2. **Fork and create your RFC**: - Fork this repository to your own GitHub account - - Copy `rfcs/0000-template.md` to `rfcs/THV-XXXX-descriptive-name.md` + - Copy `template.md` to `/-XXXX-descriptive-name.md` + (e.g. `toolhive/THV-XXXX-descriptive-name.md`) - Use the next available RFC number (check existing RFCs) - Fill in all required sections of the template @@ -92,17 +93,19 @@ If you're new to the RFC process: All RFC files must follow this naming pattern: ``` -THV-{NUMBER}-{descriptive-name}.md +{project}/{PREFIX}-{NUMBER}-{descriptive-name}.md ``` Where: +- `{project}` is the project folder (e.g. `toolhive`) +- `{PREFIX}` is that project's prefix (e.g. `THV`), listed in the [README](README.md#projects) - `{NUMBER}` is a four-digit sequential number that must be equal to the PR number (e.g., 0001, 0002) - `{descriptive-name}` is a short description in kebab-case #### Examples of valid RFC names: -- `THV-0001-token-exchange-middleware.md` -- `THV-0002-kubernetes-crd-improvements.md` -- `THV-0003-registry-api-v2.md` +- `toolhive/THV-0001-token-exchange-middleware.md` +- `toolhive/THV-0002-kubernetes-crd-improvements.md` +- `toolhive/THV-0003-registry-api-v2.md` A CI job will make sure you're following the right numbering. diff --git a/README.md b/README.md index 1dcbd63..c6beb0f 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# ToolHive RFCs +# RFCs -This repository contains Requests for Comments (RFCs) for the ToolHive ecosystem. RFCs are design documents that describe significant changes, new features, or architectural decisions across any ToolHive project. +This repository contains Requests for Comments (RFCs) for Stacklok projects, organized by project. RFCs are design documents that describe significant changes, new features, or architectural decisions. ## What is an RFC? -An RFC (Request for Comments) is a design document that proposes a significant change to the ToolHive ecosystem. RFCs provide a consistent and controlled path for new features and changes to enter the project, ensuring that all stakeholders have an opportunity to provide feedback. +An RFC (Request for Comments) is a design document that proposes a significant change to a project. RFCs provide a consistent and controlled path for new features and changes to enter the project, ensuring that all stakeholders have an opportunity to provide feedback. ## When to Write an RFC @@ -25,17 +25,15 @@ You probably **don't** need an RFC for: - Performance improvements that don't change behavior - Changes isolated to a single component with no external impact -## ToolHive Ecosystem +## Projects -This RFC repository serves the entire ToolHive ecosystem, including but not limited to: +Each project has its own folder, filename prefix and README describing its scope. -| Repository | Description | -|------------|-------------| -| [toolhive](https://github.com/stacklok/toolhive) | Core ToolHive runtime and CLI | -| [toolhive-studio](https://github.com/stacklok/toolhive-studio) | Desktop application for managing MCP servers | -| [toolhive-registry](https://github.com/stacklok/toolhive-registry) | ToolHive's registry of MCP servers | -| [toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server) | API server implementing the MCP Registry API | -| [toolhive-cloud-ui](https://github.com/stacklok/toolhive-cloud-ui) | Cloud UI for MCP servers | +| Project | Folder | Prefix | +|---------|--------|--------| +| ToolHive ecosystem | [`toolhive/`](toolhive/) | `THV-` | + +To onboard a new project, create `/README.md`, pick a short prefix, and register the folder and prefix in the `PREFIXES` map in `.github/workflows/validate-proposal-naming.yml`. ## RFC Process @@ -46,7 +44,7 @@ Before writing a full RFC, consider opening a thread on [Discord](https://discor ### 2. Create the RFC 1. Fork this repository -2. Copy `rfcs/0000-template.md` to `rfcs/XXXX-descriptive-name.md` +2. Copy `template.md` to `/-XXXX-descriptive-name.md` (e.g. `toolhive/THV-XXXX-descriptive-name.md`) - Use the next available Pull Request number for your RFC (check existing RFCs) - Use a short, descriptive name with hyphens 3. Fill in the RFC template @@ -76,19 +74,20 @@ Once accepted, the RFC can be implemented. The RFC should be updated with: ## RFC Numbering -RFCs are numbered based on the PR numbers, so they are incremental, but not necessarily sequential (0001, 0002, 0004, etc.). When creating a new RFC, check the existing RFCs and use the next available number. A CI task will ensure you're using the right number. +RFCs are numbered based on the PR numbers, so they are incremental, but not necessarily sequential (0001, 0002, 0004, etc.). The number sequence is shared across all projects; only the prefix differs. When creating a new RFC, check the existing RFCs and use the next available number. A CI task will ensure you're using the right number. For RFCs that originate from issues in specific repositories, you may reference the issue number in the RFC (e.g., "This RFC addresses toolhive#1234"). ## Directory Structure ``` -toolhive-rfcs/ +rfcs/ ├── README.md # This file ├── CONTRIBUTING.md # Contribution guidelines -├── rfcs/ -│ ├── 0000-template.md # RFC template -│ └── ... +├── template.md # RFC template shared by all projects +├── toolhive/ # One folder per project +│ ├── README.md # Project scope and related repositories +│ └── THV-XXXX-*.md # RFCs, prefixed per project └── assets/ # Images and diagrams for RFCs └── XXXX/ # Assets for RFC XXXX ``` diff --git a/SECURITY.md b/SECURITY.md index d43a295..7c8c729 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -20,7 +20,7 @@ the appropriate repository: If you discover a security issue in an RFC design that could lead to vulnerabilities in implementations, please use the GitHub Security Advisory -["Report a Vulnerability"](https://github.com/stacklok/toolhive-rfcs/security/advisories/new) +["Report a Vulnerability"](https://github.com/stacklok/rfcs/security/advisories/new) tab. If you are unable to access GitHub you can also email us at diff --git a/rfcs/0000-template.md b/template.md similarity index 97% rename from rfcs/0000-template.md rename to template.md index 7711a43..af2ce21 100644 --- a/rfcs/0000-template.md +++ b/template.md @@ -4,7 +4,7 @@ - **Author(s)**: Your Name (@github-handle) - **Created**: YYYY-MM-DD - **Last Updated**: YYYY-MM-DD -- **Target Repository**: toolhive | toolhive-studio | toolhive-registry | toolhive-registry-server | multiple +- **Target Repository**: the repository this RFC targets (e.g. toolhive, toolhive-studio, toolhive-registry-server) | multiple - **Related Issues**: [toolhive#1234](https://github.com/stacklok/toolhive/issues/1234) (if applicable) ## Summary diff --git a/toolhive/README.md b/toolhive/README.md new file mode 100644 index 0000000..008e872 --- /dev/null +++ b/toolhive/README.md @@ -0,0 +1,17 @@ +# ToolHive RFCs + +RFCs for the ToolHive ecosystem. Files in this folder use the `THV-` prefix, for example `THV-0083-stateless-vmcp.md`. + +## ToolHive Ecosystem + +RFCs here can target any of the following repositories, or span several of them: + +| Repository | Description | +|------------|-------------| +| [toolhive](https://github.com/stacklok/toolhive) | Core ToolHive runtime and CLI | +| [toolhive-studio](https://github.com/stacklok/toolhive-studio) | Desktop application for managing MCP servers | +| [toolhive-registry](https://github.com/stacklok/toolhive-registry) | ToolHive's registry of MCP servers | +| [toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server) | API server implementing the MCP Registry API | +| [toolhive-cloud-ui](https://github.com/stacklok/toolhive-cloud-ui) | Cloud UI for MCP servers | + +For the RFC process, template and naming rules, see the [repository README](../README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/rfcs/THV-0001-otel-integration-proposal.md b/toolhive/THV-0001-otel-integration-proposal.md similarity index 100% rename from rfcs/THV-0001-otel-integration-proposal.md rename to toolhive/THV-0001-otel-integration-proposal.md diff --git a/rfcs/THV-0003-toolhive-kubernetes-architecture-improvement.md b/toolhive/THV-0003-toolhive-kubernetes-architecture-improvement.md similarity index 100% rename from rfcs/THV-0003-toolhive-kubernetes-architecture-improvement.md rename to toolhive/THV-0003-toolhive-kubernetes-architecture-improvement.md diff --git a/rfcs/THV-0004-upstream-mcp-registry-format-support.md b/toolhive/THV-0004-upstream-mcp-registry-format-support.md similarity index 100% rename from rfcs/THV-0004-upstream-mcp-registry-format-support.md rename to toolhive/THV-0004-upstream-mcp-registry-format-support.md diff --git a/rfcs/THV-0005-environment-variable-secrets-fallback.md b/toolhive/THV-0005-environment-variable-secrets-fallback.md similarity index 100% rename from rfcs/THV-0005-environment-variable-secrets-fallback.md rename to toolhive/THV-0005-environment-variable-secrets-fallback.md diff --git a/rfcs/THV-0006-groups-in-registry.md b/toolhive/THV-0006-groups-in-registry.md similarity index 100% rename from rfcs/THV-0006-groups-in-registry.md rename to toolhive/THV-0006-groups-in-registry.md diff --git a/rfcs/THV-0007-token-exchange-middleware.md b/toolhive/THV-0007-token-exchange-middleware.md similarity index 100% rename from rfcs/THV-0007-token-exchange-middleware.md rename to toolhive/THV-0007-token-exchange-middleware.md diff --git a/rfcs/THV-0008-virtual-mcp-server.md b/toolhive/THV-0008-virtual-mcp-server.md similarity index 100% rename from rfcs/THV-0008-virtual-mcp-server.md rename to toolhive/THV-0008-virtual-mcp-server.md diff --git a/rfcs/THV-0009-remote-mcp-proxy.md b/toolhive/THV-0009-remote-mcp-proxy.md similarity index 100% rename from rfcs/THV-0009-remote-mcp-proxy.md rename to toolhive/THV-0009-remote-mcp-proxy.md diff --git a/rfcs/THV-0010-kubernetes-mcpgroup-crd.md b/toolhive/THV-0010-kubernetes-mcpgroup-crd.md similarity index 100% rename from rfcs/THV-0010-kubernetes-mcpgroup-crd.md rename to toolhive/THV-0010-kubernetes-mcpgroup-crd.md diff --git a/rfcs/THV-0011-refactor-mcpregistry-controller.md b/toolhive/THV-0011-refactor-mcpregistry-controller.md similarity index 100% rename from rfcs/THV-0011-refactor-mcpregistry-controller.md rename to toolhive/THV-0011-refactor-mcpregistry-controller.md diff --git a/rfcs/THV-0012-custom-package-registries.md b/toolhive/THV-0012-custom-package-registries.md similarity index 100% rename from rfcs/THV-0012-custom-package-registries.md rename to toolhive/THV-0012-custom-package-registries.md diff --git a/rfcs/THV-0013-kubernetes-registry-source-type.md b/toolhive/THV-0013-kubernetes-registry-source-type.md similarity index 100% rename from rfcs/THV-0013-kubernetes-registry-source-type.md rename to toolhive/THV-0013-kubernetes-registry-source-type.md diff --git a/rfcs/THV-0014-vmcp-k8s-aware-refactor.md b/toolhive/THV-0014-vmcp-k8s-aware-refactor.md similarity index 100% rename from rfcs/THV-0014-vmcp-k8s-aware-refactor.md rename to toolhive/THV-0014-vmcp-k8s-aware-refactor.md diff --git a/rfcs/THV-0015-tool-definitions-extension.md b/toolhive/THV-0015-tool-definitions-extension.md similarity index 100% rename from rfcs/THV-0015-tool-definitions-extension.md rename to toolhive/THV-0015-tool-definitions-extension.md diff --git a/rfcs/THV-0017-dynamic-webhook-middleware.md b/toolhive/THV-0017-dynamic-webhook-middleware.md similarity index 100% rename from rfcs/THV-0017-dynamic-webhook-middleware.md rename to toolhive/THV-0017-dynamic-webhook-middleware.md diff --git a/rfcs/THV-0019-auth-server-design.md b/toolhive/THV-0019-auth-server-design.md similarity index 100% rename from rfcs/THV-0019-auth-server-design.md rename to toolhive/THV-0019-auth-server-design.md diff --git a/rfcs/THV-0019-auth-server-overview.md b/toolhive/THV-0019-auth-server-overview.md similarity index 100% rename from rfcs/THV-0019-auth-server-overview.md rename to toolhive/THV-0019-auth-server-overview.md diff --git a/rfcs/THV-0020-desktop-cli-version-alignment.md b/toolhive/THV-0020-desktop-cli-version-alignment.md similarity index 100% rename from rfcs/THV-0020-desktop-cli-version-alignment.md rename to toolhive/THV-0020-desktop-cli-version-alignment.md diff --git a/rfcs/THV-0021-thvignore.md b/toolhive/THV-0021-thvignore.md similarity index 100% rename from rfcs/THV-0021-thvignore.md rename to toolhive/THV-0021-thvignore.md diff --git a/rfcs/THV-0022-optimizer-migration-to-vmcp.md b/toolhive/THV-0022-optimizer-migration-to-vmcp.md similarity index 100% rename from rfcs/THV-0022-optimizer-migration-to-vmcp.md rename to toolhive/THV-0022-optimizer-migration-to-vmcp.md diff --git a/rfcs/THV-0023-crd-v1beta1-optimization.md b/toolhive/THV-0023-crd-v1beta1-optimization.md similarity index 100% rename from rfcs/THV-0023-crd-v1beta1-optimization.md rename to toolhive/THV-0023-crd-v1beta1-optimization.md diff --git a/rfcs/THV-0026-header-passthrough.md b/toolhive/THV-0026-header-passthrough.md similarity index 100% rename from rfcs/THV-0026-header-passthrough.md rename to toolhive/THV-0026-header-passthrough.md diff --git a/rfcs/THV-0029-skills-support-registry-server.md b/toolhive/THV-0029-skills-support-registry-server.md similarity index 100% rename from rfcs/THV-0029-skills-support-registry-server.md rename to toolhive/THV-0029-skills-support-registry-server.md diff --git a/rfcs/THV-0030-skills-lifecycle-management.md b/toolhive/THV-0030-skills-lifecycle-management.md similarity index 100% rename from rfcs/THV-0030-skills-lifecycle-management.md rename to toolhive/THV-0030-skills-lifecycle-management.md diff --git a/rfcs/THV-0031-auth-server-integration.md b/toolhive/THV-0031-auth-server-integration.md similarity index 100% rename from rfcs/THV-0031-auth-server-integration.md rename to toolhive/THV-0031-auth-server-integration.md diff --git a/rfcs/THV-0032-toolhive-core-shared-library.md b/toolhive/THV-0032-toolhive-core-shared-library.md similarity index 100% rename from rfcs/THV-0032-toolhive-core-shared-library.md rename to toolhive/THV-0032-toolhive-core-shared-library.md diff --git a/rfcs/THV-0033-aws-sts-agent-delegation.md b/toolhive/THV-0033-aws-sts-agent-delegation.md similarity index 100% rename from rfcs/THV-0033-aws-sts-agent-delegation.md rename to toolhive/THV-0033-aws-sts-agent-delegation.md diff --git a/rfcs/THV-0034-long-running-local-server.md b/toolhive/THV-0034-long-running-local-server.md similarity index 100% rename from rfcs/THV-0034-long-running-local-server.md rename to toolhive/THV-0034-long-running-local-server.md diff --git a/rfcs/THV-0035-auth-server-redis-storage.md b/toolhive/THV-0035-auth-server-redis-storage.md similarity index 100% rename from rfcs/THV-0035-auth-server-redis-storage.md rename to toolhive/THV-0035-auth-server-redis-storage.md diff --git a/rfcs/THV-0038-session-scoped-client-lifecycle.md b/toolhive/THV-0038-session-scoped-client-lifecycle.md similarity index 100% rename from rfcs/THV-0038-session-scoped-client-lifecycle.md rename to toolhive/THV-0038-session-scoped-client-lifecycle.md diff --git a/rfcs/THV-0041-sqlite-state-management.md b/toolhive/THV-0041-sqlite-state-management.md similarity index 100% rename from rfcs/THV-0041-sqlite-state-management.md rename to toolhive/THV-0041-sqlite-state-management.md diff --git a/rfcs/THV-0043-registry-authentication.md b/toolhive/THV-0043-registry-authentication.md similarity index 100% rename from rfcs/THV-0043-registry-authentication.md rename to toolhive/THV-0043-registry-authentication.md diff --git a/rfcs/THV-0047-vmcp-proxyrunner-horizontal-scaling.md b/toolhive/THV-0047-vmcp-proxyrunner-horizontal-scaling.md similarity index 100% rename from rfcs/THV-0047-vmcp-proxyrunner-horizontal-scaling.md rename to toolhive/THV-0047-vmcp-proxyrunner-horizontal-scaling.md diff --git a/rfcs/THV-0050-embedded-as-with-aws-sts.md b/toolhive/THV-0050-embedded-as-with-aws-sts.md similarity index 100% rename from rfcs/THV-0050-embedded-as-with-aws-sts.md rename to toolhive/THV-0050-embedded-as-with-aws-sts.md diff --git a/rfcs/THV-0052-multi-upstream-idp-authserver.md b/toolhive/THV-0052-multi-upstream-idp-authserver.md similarity index 100% rename from rfcs/THV-0052-multi-upstream-idp-authserver.md rename to toolhive/THV-0052-multi-upstream-idp-authserver.md diff --git a/rfcs/THV-0053-vmcp-embedded-authserver.md b/toolhive/THV-0053-vmcp-embedded-authserver.md similarity index 100% rename from rfcs/THV-0053-vmcp-embedded-authserver.md rename to toolhive/THV-0053-vmcp-embedded-authserver.md diff --git a/rfcs/THV-0054-vmcp-upstream-inject-strategy.md b/toolhive/THV-0054-vmcp-upstream-inject-strategy.md similarity index 100% rename from rfcs/THV-0054-vmcp-upstream-inject-strategy.md rename to toolhive/THV-0054-vmcp-upstream-inject-strategy.md diff --git a/rfcs/THV-0055-mcpserverentry-direct-remote-backends.md b/toolhive/THV-0055-mcpserverentry-direct-remote-backends.md similarity index 100% rename from rfcs/THV-0055-mcpserverentry-direct-remote-backends.md rename to toolhive/THV-0055-mcpserverentry-direct-remote-backends.md diff --git a/rfcs/THV-0056-scoped-secret-store.md b/toolhive/THV-0056-scoped-secret-store.md similarity index 100% rename from rfcs/THV-0056-scoped-secret-store.md rename to toolhive/THV-0056-scoped-secret-store.md diff --git a/rfcs/THV-0057-rate-limiting.md b/toolhive/THV-0057-rate-limiting.md similarity index 100% rename from rfcs/THV-0057-rate-limiting.md rename to toolhive/THV-0057-rate-limiting.md diff --git a/rfcs/THV-0059-vmcp-local-experience.md b/toolhive/THV-0059-vmcp-local-experience.md similarity index 100% rename from rfcs/THV-0059-vmcp-local-experience.md rename to toolhive/THV-0059-vmcp-local-experience.md diff --git a/rfcs/THV-0068-workload-upgrade.md b/toolhive/THV-0068-workload-upgrade.md similarity index 100% rename from rfcs/THV-0068-workload-upgrade.md rename to toolhive/THV-0068-workload-upgrade.md diff --git a/rfcs/THV-0070-thv-llm-subcommand.md b/toolhive/THV-0070-thv-llm-subcommand.md similarity index 100% rename from rfcs/THV-0070-thv-llm-subcommand.md rename to toolhive/THV-0070-thv-llm-subcommand.md diff --git a/rfcs/THV-0071-cimd-support.md b/toolhive/THV-0071-cimd-support.md similarity index 100% rename from rfcs/THV-0071-cimd-support.md rename to toolhive/THV-0071-cimd-support.md diff --git a/rfcs/THV-0072-vmcp-multi-upstream-partial-auth.md b/toolhive/THV-0072-vmcp-multi-upstream-partial-auth.md similarity index 100% rename from rfcs/THV-0072-vmcp-multi-upstream-partial-auth.md rename to toolhive/THV-0072-vmcp-multi-upstream-partial-auth.md diff --git a/rfcs/THV-0073-vmcp-session-identity-binding.md b/toolhive/THV-0073-vmcp-session-identity-binding.md similarity index 100% rename from rfcs/THV-0073-vmcp-session-identity-binding.md rename to toolhive/THV-0073-vmcp-session-identity-binding.md diff --git a/rfcs/THV-0076-vmcp-core-interface.md b/toolhive/THV-0076-vmcp-core-interface.md similarity index 100% rename from rfcs/THV-0076-vmcp-core-interface.md rename to toolhive/THV-0076-vmcp-core-interface.md diff --git a/rfcs/THV-0077-plugins-lifecycle-management.md b/toolhive/THV-0077-plugins-lifecycle-management.md similarity index 100% rename from rfcs/THV-0077-plugins-lifecycle-management.md rename to toolhive/THV-0077-plugins-lifecycle-management.md diff --git a/rfcs/THV-0078-decouple-vmcp-config-from-crd.md b/toolhive/THV-0078-decouple-vmcp-config-from-crd.md similarity index 100% rename from rfcs/THV-0078-decouple-vmcp-config-from-crd.md rename to toolhive/THV-0078-decouple-vmcp-config-from-crd.md diff --git a/rfcs/THV-0079-cross-app-access-grant.md b/toolhive/THV-0079-cross-app-access-grant.md similarity index 100% rename from rfcs/THV-0079-cross-app-access-grant.md rename to toolhive/THV-0079-cross-app-access-grant.md diff --git a/rfcs/THV-0080-skills-lock-file.md b/toolhive/THV-0080-skills-lock-file.md similarity index 100% rename from rfcs/THV-0080-skills-lock-file.md rename to toolhive/THV-0080-skills-lock-file.md diff --git a/rfcs/THV-0081-stateless-transport-proxies.md b/toolhive/THV-0081-stateless-transport-proxies.md similarity index 100% rename from rfcs/THV-0081-stateless-transport-proxies.md rename to toolhive/THV-0081-stateless-transport-proxies.md diff --git a/rfcs/THV-0083-stateless-vmcp.md b/toolhive/THV-0083-stateless-vmcp.md similarity index 100% rename from rfcs/THV-0083-stateless-vmcp.md rename to toolhive/THV-0083-stateless-vmcp.md From 29c738126f1a49c1cd14d63b13becfc2b1bb9093 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 6 Oct 2026 14:59:54 +0300 Subject: [PATCH 2/4] Add mecatl project folder Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Radoslav Dimitrov --- .github/workflows/validate-proposal-naming.yml | 1 + README.md | 1 + mecatl/README.md | 17 +++++++++++++++++ 3 files changed, 19 insertions(+) create mode 100644 mecatl/README.md diff --git a/.github/workflows/validate-proposal-naming.yml b/.github/workflows/validate-proposal-naming.yml index 0f04d98..bc36d46 100644 --- a/.github/workflows/validate-proposal-naming.yml +++ b/.github/workflows/validate-proposal-naming.yml @@ -40,6 +40,7 @@ jobs: # Map of project folder -> RFC filename prefix. Add a line here when onboarding a new project. declare -A PREFIXES=( [toolhive]="THV" + [mecatl]="MEC" ) # Get the list of NEW files added in a project folder (not modifications to existing files). diff --git a/README.md b/README.md index c6beb0f..82c60e5 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Each project has its own folder, filename prefix and README describing its scope | Project | Folder | Prefix | |---------|--------|--------| | ToolHive ecosystem | [`toolhive/`](toolhive/) | `THV-` | +| Mecatl | [`mecatl/`](mecatl/) | `MEC-` | To onboard a new project, create `/README.md`, pick a short prefix, and register the folder and prefix in the `PREFIXES` map in `.github/workflows/validate-proposal-naming.yml`. diff --git a/mecatl/README.md b/mecatl/README.md new file mode 100644 index 0000000..008c5aa --- /dev/null +++ b/mecatl/README.md @@ -0,0 +1,17 @@ +# Mecatl RFCs + +RFCs for Mecatl. Files in this folder use the `MEC-` prefix, for example `MEC-0090-example-proposal.md`. + +## Scope + + + +## Repositories + + + +| Repository | Description | +|------------|-------------| +| | | + +For the RFC process, template and naming rules, see the [repository README](../README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). From 9f92fc2f0c2362af875072a6d76f6adffc9e6308 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 6 Oct 2026 15:12:36 +0300 Subject: [PATCH 3/4] Replace project READMEs with AGENTS.md and make skills project-agnostic Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Radoslav Dimitrov --- .../skills/respond-to-rfc-comments/SKILL.md | 6 +- .claude/skills/review-rfc/SKILL.md | 69 ++-------- .claude/skills/write-rfc/SKILL.md | 130 +++--------------- AGENTS.md | 55 ++++++++ CLAUDE.md | 1 + README.md | 11 +- mecatl/AGENTS.md | 30 ++++ mecatl/README.md | 17 --- template.md | 4 +- toolhive/AGENTS.md | 76 ++++++++++ toolhive/README.md | 17 --- 11 files changed, 210 insertions(+), 206 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 mecatl/AGENTS.md delete mode 100644 mecatl/README.md create mode 100644 toolhive/AGENTS.md delete mode 100644 toolhive/README.md diff --git a/.claude/skills/respond-to-rfc-comments/SKILL.md b/.claude/skills/respond-to-rfc-comments/SKILL.md index 91befb0..2460094 100644 --- a/.claude/skills/respond-to-rfc-comments/SKILL.md +++ b/.claude/skills/respond-to-rfc-comments/SKILL.md @@ -1,6 +1,6 @@ --- name: respond-to-rfc-comments -description: Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects. +description: Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for any project in this repository (toolhive, mecatl, ...). allowed-tools: Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Edit, Write, AskUserQuestion --- @@ -24,7 +24,7 @@ Gather all review feedback from the PR: ### Step 2: Read the RFC -Read the full RFC document so you have context for every comment. +Read the full RFC document so you have context for every comment. Also read the root `AGENTS.md` and the `AGENTS.md` in the RFC's project folder, so proposed changes follow the project's conventions. ### Step 3: Present Comments One at a Time @@ -85,7 +85,7 @@ After replies are posted, ask the user if they want to commit and push. If confi - When renaming fields or terms, use `replace_all` to catch every occurrence. - When adding new sections, match the style of existing sections in the RFC. - When adding sections required by the template (e.g., Security Considerations), reference existing RFCs in the repo for structural patterns: - - Search for the section name across `rfcs/THV-*.md` files. + - Search for the section name across `/*.md` files. - Use 2-3 examples to match the established format (threat model tables, subsection structure, etc.). ### PR-Level Comment Responses diff --git a/.claude/skills/review-rfc/SKILL.md b/.claude/skills/review-rfc/SKILL.md index ceff065..fd8f7b2 100644 --- a/.claude/skills/review-rfc/SKILL.md +++ b/.claude/skills/review-rfc/SKILL.md @@ -1,12 +1,12 @@ --- name: review-rfc -description: Review RFCs for the ToolHive ecosystem. Use when the user wants to review, critique, or provide feedback on an RFC for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects. +description: Review RFCs for any project in this repository (toolhive, mecatl, ...). Use when the user wants to review, critique, or provide feedback on an RFC, including ones for the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard repositories. allowed-tools: Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Task --- # Review RFC Skill -This skill helps you thoroughly review RFCs for the ToolHive ecosystem, ensuring they meet quality standards, architectural alignment, and security requirements. +This skill helps you thoroughly review RFCs for the projects in this repository, ensuring they meet quality standards, architectural alignment, and security requirements. ## Overview @@ -18,27 +18,13 @@ When reviewing an RFC, you should evaluate it against multiple dimensions: compl First, read the RFC document completely. If provided a PR number or file path, fetch and read it. -### Step 2: Fetch Architectural Context +### Step 2: Load Project Context -Before reviewing, gather context from the ToolHive architecture documentation. Use `mcp__github__get_file_contents` to read relevant docs from `stacklok/toolhive` repo's `docs/arch/` directory: - -| Document | When to Read | -|----------|--------------| -| `00-overview.md` | Always - understand platform concepts | -| `01-deployment-modes.md` | RFCs affecting deployment, K8s, or local mode | -| `02-core-concepts.md` | RFCs introducing new concepts or terminology | -| `03-transport-architecture.md` | RFCs affecting MCP transports or proxy | -| `04-secrets-management.md` | RFCs involving secrets or credentials | -| `05-runconfig-and-permissions.md` | RFCs affecting configuration or permissions | -| `06-registry-system.md` | RFCs affecting registry functionality | -| `07-groups.md` | RFCs involving server grouping | -| `08-workloads-lifecycle.md` | RFCs affecting workload management | -| `09-operator-architecture.md` | RFCs affecting K8s operator or CRDs | -| `10-virtual-mcp-architecture.md` | RFCs involving aggregation or virtual MCP | +Read the root `AGENTS.md`, then the `AGENTS.md` in the RFC's project folder. Use its "Research before writing or reviewing" section to fetch the architecture docs relevant to this RFC (for example with `mcp__github__get_file_contents`), and use its architecture summary, design principles and conventions as the standard to review against. ### Step 3: Check Related Existing RFCs -Search this repository for related RFCs that might: +Search the project folder for related RFCs that might: - Conflict with the proposal - Be superseded by the proposal - Provide context or dependencies @@ -92,12 +78,11 @@ The Security Considerations section MUST address all of these: ### C. Technical Accuracy -- [ ] **Correct terminology**: Uses ToolHive concepts correctly (Workloads, Transports, Middleware, etc.) -- [ ] **Architecture alignment**: Follows established patterns and principles +- [ ] **Correct terminology**: Uses the project's concepts correctly (see the project's `AGENTS.md`) +- [ ] **Architecture alignment**: Follows the design principles in the project's `AGENTS.md` - [ ] **Code examples**: Syntactically correct, idiomatic for the language - [ ] **API design**: Consistent with existing APIs in the target repo -- [ ] **CRD design**: Follows Kubernetes conventions if applicable -- [ ] **Configuration format**: Matches existing RunConfig patterns +- [ ] **Project conventions**: Follows the "Conventions" section of the project's `AGENTS.md` (CRDs, configuration formats, etc.) ### D. Diagrams and Examples @@ -114,35 +99,9 @@ The Security Considerations section MUST address all of these: - [ ] **Performance impact**: Considered where relevant? - [ ] **Cross-repo impact**: If `multiple` repos, are all impacts identified? -## ToolHive Ecosystem Context - -### Target Repositories - -| Repository | Type | Key Considerations | -|------------|------|-------------------| -| `toolhive` | Go | Core platform, CLI, operator, proxy, virtual MCP | -| `toolhive-studio` | TypeScript | Desktop UI, Electron app | -| `toolhive-registry-server` | Go | Registry API, MCP Registry spec compliance | -| `toolhive-registry` | Go/JSON | Registry data, server definitions | -| `toolhive-cloud-ui` | TypeScript/Next.js | Cloud UI, OIDC integration | -| `dockyard` | Go | Container packaging, security scanning | - -### Key Architecture Principles to Verify - -1. **Platform, not runner**: Does this enhance the platform abstraction? -2. **Security by default**: Does this maintain or improve security posture? -3. **Middleware composability**: Can this be implemented as middleware if appropriate? -4. **RunConfig portability**: Does this preserve configuration portability? -5. **Cloud-native**: Is this Kubernetes-friendly where applicable? - -### CRD Types (for K8s-related RFCs) +## Project Context -- `MCPServer` - Individual MCP server deployment -- `MCPRegistry` - Registry configuration -- `MCPToolConfig` - Tool filtering and configuration -- `MCPExternalAuthConfig` - External authentication -- `MCPGroup` - Server grouping -- `VirtualMCPServer` - Aggregation of multiple servers +Target repositories, architecture principles to verify, and domain-specific checks (such as CRD types for Kubernetes RFCs) are defined per project in `/AGENTS.md`. Verify the RFC against each design principle listed there. ## Review Output Format @@ -172,7 +131,7 @@ Structure your review as follows: [Specific feedback on the security section] ### Architectural Alignment -[How well does this align with ToolHive architecture?] +[How well does this align with the project's architecture and design principles?] ### Questions for the Author - [Clarifying questions that need answers] @@ -212,6 +171,8 @@ Structure your review as follows: ## Reference Files -- Template: `rfcs/0000-template.md` +- Shared rules: `AGENTS.md` +- Project rules: `/AGENTS.md` +- Template: `template.md` - Contributing guide: `CONTRIBUTING.md` -- Existing RFCs: `rfcs/THV-*.md` +- Existing RFCs: `/*.md` diff --git a/.claude/skills/write-rfc/SKILL.md b/.claude/skills/write-rfc/SKILL.md index 03e9696..e04b963 100644 --- a/.claude/skills/write-rfc/SKILL.md +++ b/.claude/skills/write-rfc/SKILL.md @@ -1,76 +1,40 @@ --- name: write-rfc -description: Write RFCs for the ToolHive ecosystem. Use when the user wants to create a new RFC, proposal, or design document for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects. +description: Write RFCs for any project in this repository (toolhive, mecatl, ...). Use when the user wants to create a new RFC, proposal, or design document for a project covered here, including the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard repositories. allowed-tools: Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Task, Edit, Write, AskUserQuestion --- # Write RFC Skill -This skill helps you write high-quality RFCs for the ToolHive ecosystem following established patterns and conventions. +This skill helps you write high-quality RFCs for the projects in this repository 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. +RFCs live in one folder per project and are named `/-{NUMBER}-{descriptive-name}.md`. The NUMBER must match the PR number and be zero-padded to 4 digits. Project-specific knowledge (scope, repositories, architecture docs, conventions) lives in `/AGENTS.md`, not in this skill. ## Workflow -### Step 1: Gather Requirements +### Step 1: Identify the Project and Gather Requirements -Before writing an RFC, ask the user about: +1. Read the root `AGENTS.md`. +2. Determine the project (folder). If the user hasn't said, ask. Then read `/AGENTS.md`; it defines the prefix, target repositories, architecture docs and conventions. + +Then 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 +2. **Target Repository**: Which repository does this affect? Offer the list from the project's `AGENTS.md`, plus `multiple` for 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 +### Step 2: Research -Read `rfcs/` directory in this repository to understand patterns and check for related proposals. +Before drafting: -#### 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 | +1. Read the architecture docs and code locations listed under "Research before writing or reviewing" in the project's `AGENTS.md` (use `mcp__github__get_file_contents` or `mcp__github__search_code`). +2. Read the existing RFCs in `/` to understand patterns and find related proposals. ### Step 3: Draft the RFC -Create the RFC following the template structure from `rfcs/0000-template.md`. +Create the RFC following the template structure from `template.md`. #### Required Metadata @@ -117,31 +81,14 @@ Every RFC MUST address: ### Step 4: Use Proper Conventions -#### Code Examples +Follow the "Conventions" section of the project's `AGENTS.md` (code example languages, API and CRD conventions, terminology). Generally: -- 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. +Name the file `/-XXXX-{descriptive-name}.md`, where `` comes from the project's `AGENTS.md` and XXXX is the PR number. Since you don't know the PR number yet, use the `XXXX` placeholder and remind the user to rename the file to match the PR number after creating the PR. ### Step 6: Review Checklist @@ -155,46 +102,13 @@ Before finalizing, verify: - [ ] 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 +- [ ] File is in the project folder and follows the naming convention +- [ ] Project-specific conventions from `/AGENTS.md` are followed ## Reference Files -- Template: `rfcs/0000-template.md` +- Shared rules: `AGENTS.md` +- Project rules: `/AGENTS.md` +- Template: `template.md` - Contributing guide: `CONTRIBUTING.md` -- Existing RFCs: `rfcs/THV-*.md` +- Existing RFCs: `/*.md` diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b841387 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,55 @@ +# RFC repository guidelines + +This repository holds design documents (RFCs) for Stacklok projects, one folder per project. These rules apply to every project. Each project folder has its own `AGENTS.md` with project-specific rules; **read the root file and the file in the project folder you are working in before writing, reviewing or editing an RFC.** + +## Layout + +``` +template.md Shared RFC template +/ One folder per project +├── AGENTS.md Project scope, repositories, architecture context, conventions +└── -NNNN-descriptive-name.md +``` + +| Project | Folder | Prefix | Guidelines | +|---------|--------|--------|------------| +| ToolHive ecosystem | `toolhive/` | `THV` | [toolhive/AGENTS.md](toolhive/AGENTS.md) | +| Mecatl | `mecatl/` | `MEC` | [mecatl/AGENTS.md](mecatl/AGENTS.md) | + +If the user doesn't say which project an RFC belongs to, ask. Never create RFCs at the repository root. + +## File naming + +`/--.md`, for example `toolhive/THV-0083-stateless-vmcp.md`. + +- `NNNN` is the pull request number, zero-padded to four digits. The sequence is shared across projects; only the prefix differs. +- The PR number isn't known until the PR exists. Draft as `-XXXX-.md` and tell the user to rename the file once the PR is opened. +- CI (`.github/workflows/validate-proposal-naming.yml`) rejects new files whose folder isn't registered in its `PREFIXES` map or whose name doesn't match the rule above. + +## Writing an RFC + +1. Start from [`template.md`](template.md). Keep its section order. A section that doesn't apply gets a one-line justification, not deletion. +2. Fill in the metadata block: Status (`Draft` for new RFCs), Author(s), Created, Last Updated, Target Repository, Related Issues. +3. **Security Considerations is required for every RFC.** Address all of: Threat Model, Authentication and Authorization, Data Security, Input Validation, Secrets Management, Audit and Logging, Mitigations. "N/A" needs a reason. +4. Use Mermaid for diagrams, concrete examples instead of placeholders, and never put real secrets in examples. +5. Keep each RFC to one cohesive change. Split large proposals. +6. Read the existing RFCs in the project folder first. Check for ones that overlap, conflict with or are superseded by the proposal. +7. Commits need a `Signed-off-by` trailer (Developer Certificate of Origin). PR titles look like `RFC: `. + +## Reviewing an RFC + +Check, in order: structure and completeness against the template; security section (all seven areas, no unjustified "N/A", no threat model missing for network-exposed features); technical accuracy against the project's architecture context; diagrams and examples; feasibility, phasing and cross-repo impact. Also apply the project's own review checks from its `AGENTS.md`. + +## Lifecycle + +Statuses: Draft, Under Review, Accepted, Rejected, Implemented, Superseded. After acceptance, update the RFC with implementation PR links, deviations from the design, and the final status. + +## Skills + +The `write-rfc`, `review-rfc` and `respond-to-rfc-comments` skills in `.claude/skills/` work for every project. They take project-specific knowledge from the project's `AGENTS.md`, so put it there rather than in a skill. + +## Adding a project + +1. Create `/AGENTS.md` (copy `mecatl/AGENTS.md` as a starting point). +2. Register the folder and prefix in the `PREFIXES` map in `.github/workflows/validate-proposal-naming.yml`. +3. Add a row to the table above and to the Projects table in `README.md`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/README.md b/README.md index 82c60e5..baaafd0 100644 --- a/README.md +++ b/README.md @@ -27,14 +27,14 @@ You probably **don't** need an RFC for: ## Projects -Each project has its own folder, filename prefix and README describing its scope. +Each project has its own folder, filename prefix and `AGENTS.md` describing its scope, repositories and conventions. Because most RFCs are drafted with AI assistance, that file is where project guidelines live: AI tools read it automatically, and it is just as readable by people. | Project | Folder | Prefix | |---------|--------|--------| -| ToolHive ecosystem | [`toolhive/`](toolhive/) | `THV-` | -| Mecatl | [`mecatl/`](mecatl/) | `MEC-` | +| ToolHive ecosystem | [`toolhive/`](toolhive/AGENTS.md) | `THV-` | +| Mecatl | [`mecatl/`](mecatl/AGENTS.md) | `MEC-` | -To onboard a new project, create `/README.md`, pick a short prefix, and register the folder and prefix in the `PREFIXES` map in `.github/workflows/validate-proposal-naming.yml`. +To onboard a new project, see [Adding a project](AGENTS.md#adding-a-project) in the root `AGENTS.md`. ## RFC Process @@ -85,9 +85,10 @@ For RFCs that originate from issues in specific repositories, you may reference rfcs/ ├── README.md # This file ├── CONTRIBUTING.md # Contribution guidelines +├── AGENTS.md # Shared rules for AI assistants and authors ├── template.md # RFC template shared by all projects ├── toolhive/ # One folder per project -│ ├── README.md # Project scope and related repositories +│ ├── AGENTS.md # Project scope, repositories and conventions │ └── THV-XXXX-*.md # RFCs, prefixed per project └── assets/ # Images and diagrams for RFCs └── XXXX/ # Assets for RFC XXXX diff --git a/mecatl/AGENTS.md b/mecatl/AGENTS.md new file mode 100644 index 0000000..6268d00 --- /dev/null +++ b/mecatl/AGENTS.md @@ -0,0 +1,30 @@ +# Mecatl RFC guidelines + +Project-specific rules for RFCs in `mecatl/`. The shared rules in the root [AGENTS.md](../AGENTS.md) also apply. + +- **Prefix**: `MEC` (`mecatl/MEC-NNNN-name.md`) +- **Template**: the shared [`template.md`](../template.md) + +## Scope + + + +## Repositories + + + +| Repository | Language | Description | +|------------|----------|-------------| +| | | | + +## Research before writing or reviewing + + + +## Architecture summary + + + +## Conventions + + diff --git a/mecatl/README.md b/mecatl/README.md deleted file mode 100644 index 008c5aa..0000000 --- a/mecatl/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Mecatl RFCs - -RFCs for Mecatl. Files in this folder use the `MEC-` prefix, for example `MEC-0090-example-proposal.md`. - -## Scope - - - -## Repositories - - - -| Repository | Description | -|------------|-------------| -| | | - -For the RFC process, template and naming rules, see the [repository README](../README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/template.md b/template.md index af2ce21..a299a33 100644 --- a/template.md +++ b/template.md @@ -65,7 +65,7 @@ Document any API changes, including: - Deprecated functionality ```go -// Example API change +// Example API change (use the language of the target repository) type NewInterface interface { Method(ctx context.Context, param string) (Result, error) } @@ -88,7 +88,7 @@ Describe any changes to data models, schemas, or storage. ## Security Considerations -**This section is required.** Security is a core concern for ToolHive. Address the following: +**This section is required.** Security is a core concern for every project in this repository. Address the following: ### Threat Model diff --git a/toolhive/AGENTS.md b/toolhive/AGENTS.md new file mode 100644 index 0000000..c4be1df --- /dev/null +++ b/toolhive/AGENTS.md @@ -0,0 +1,76 @@ +# ToolHive RFC guidelines + +Project-specific rules for RFCs in `toolhive/`. The shared rules in the root [AGENTS.md](../AGENTS.md) also apply. + +- **Prefix**: `THV` (`toolhive/THV-NNNN-name.md`) +- **Template**: the shared [`template.md`](../template.md) + +## Scope + +RFCs here cover the ToolHive ecosystem: changes affecting one or more of the repositories below, cross-cutting concerns, public API or user-facing behavior, security-sensitive changes, and breaking changes or deprecations. + +| Repository | Language | Description | +|------------|----------|-------------| +| [toolhive](https://github.com/stacklok/toolhive) | Go | Core platform: CLI (`thv`), operator (`thv-operator`), proxy runner (`thv-proxyrunner`), virtual MCP (`vmcp`) | +| [toolhive-studio](https://github.com/stacklok/toolhive-studio) | TypeScript | Desktop app (Electron) | +| [toolhive-registry](https://github.com/stacklok/toolhive-registry) | Go/JSON | Registry data, server definitions | +| [toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server) | Go | Registry API (`thv-registry-api`), MCP Registry spec compliance | +| [toolhive-cloud-ui](https://github.com/stacklok/toolhive-cloud-ui) | TypeScript/Next.js | Cloud/Enterprise UI, OIDC integration | +| [dockyard](https://github.com/stacklok/dockyard) | Go | Container packaging, security scanning | + +Set **Target Repository** in the metadata to one of these, or `multiple` for cross-cutting changes (then identify the impact on each repository). + +## Research before writing or reviewing + +Read the architecture docs in the `docs/arch/` directory of `stacklok/toolhive` (use `mcp__github__get_file_contents` or fetch from GitHub). Always read `00-overview.md`; read the others when relevant: + +| Document | Read when the RFC touches | +|----------|---------------------------| +| `00-overview.md` | Always: platform concepts and key components | +| `01-deployment-modes.md` | Deployment, Kubernetes or local mode | +| `02-core-concepts.md` | New concepts or terminology (Workloads, Transports, Proxy, ...) | +| `03-transport-architecture.md` | MCP transports (stdio, SSE, streamable-http) or the proxy | +| `04-secrets-management.md` | Secrets or credentials | +| `05-runconfig-and-permissions.md` | Configuration format or permission profiles | +| `06-registry-system.md` | Registry architecture, `MCPRegistry` | +| `07-groups.md` | Server grouping | +| `08-workloads-lifecycle.md` | Workload lifecycle management | +| `09-operator-architecture.md` | Kubernetes operator or CRDs | +| `10-virtual-mcp-architecture.md` | Aggregation or virtual MCP | + +Then search the target repository (`mcp__github__search_code`) to confirm the proposal fits existing code patterns, doesn't conflict with recent changes, and keeps API changes compatible. + +## Architecture summary + +ToolHive is a **platform** for MCP server management, not just a container runner: + +- A proxy layer with middleware (auth, authz, audit, rate limiting) +- Security by default (network isolation, permission profiles) +- Aggregation via the Virtual MCP Server +- A registry of curated MCP servers +- Local (CLI/UI) and Kubernetes (operator) deployment + +| Binary | Repository | Purpose | +|--------|------------|---------| +| `thv` | toolhive | Main CLI | +| `thv-operator` | toolhive | Kubernetes operator | +| `thv-proxyrunner` | toolhive | Kubernetes proxy container | +| `vmcp` | toolhive | Virtual MCP server (aggregation) | +| `thv-registry-api` | toolhive-registry-server | Registry API server | + +Transport types: **stdio** (needs protocol translation), **SSE** and **streamable-http** (transparent proxy). + +## Design principles to check + +1. **Platform, not runner**: enhances the platform abstraction. +2. **Security by default**: maintains or improves the security posture. +3. **Middleware composability**: implemented as middleware where appropriate. +4. **RunConfig portability**: keeps configuration portable (RunConfig is the portable API contract). +5. **Cloud-native**: Kubernetes-friendly where applicable. + +## Conventions + +- Code examples: **Go** for toolhive and toolhive-registry-server, **TypeScript** for toolhive-studio and toolhive-cloud-ui, **YAML** for configuration. +- Kubernetes RFCs include CRD examples (`apiVersion: toolhive.stacklok.dev/v1alpha1`). CRD types: `MCPServer`, `MCPRegistry`, `MCPToolConfig`, `MCPExternalAuthConfig`, `MCPGroup`, `VirtualMCPServer`. Follow Kubernetes API conventions. +- Use ToolHive terminology correctly (Workloads, Transports, Middleware, RunConfig, ...). +- API and configuration designs stay consistent with existing APIs and RunConfig patterns in the target repository. diff --git a/toolhive/README.md b/toolhive/README.md deleted file mode 100644 index 008e872..0000000 --- a/toolhive/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# ToolHive RFCs - -RFCs for the ToolHive ecosystem. Files in this folder use the `THV-` prefix, for example `THV-0083-stateless-vmcp.md`. - -## ToolHive Ecosystem - -RFCs here can target any of the following repositories, or span several of them: - -| Repository | Description | -|------------|-------------| -| [toolhive](https://github.com/stacklok/toolhive) | Core ToolHive runtime and CLI | -| [toolhive-studio](https://github.com/stacklok/toolhive-studio) | Desktop application for managing MCP servers | -| [toolhive-registry](https://github.com/stacklok/toolhive-registry) | ToolHive's registry of MCP servers | -| [toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server) | API server implementing the MCP Registry API | -| [toolhive-cloud-ui](https://github.com/stacklok/toolhive-cloud-ui) | Cloud UI for MCP servers | - -For the RFC process, template and naming rules, see the [repository README](../README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). From 4441b51e82f15589db4ae8a5d5e8acf7600c4600 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 6 Oct 2026 15:16:29 +0300 Subject: [PATCH 4/4] Address review findings - Exclude AGENTS.md/CLAUDE.md from the naming check - Replace absolute links to the old rfcs/ path with relative links - Align numbering, status lists and directory tree across docs - Make shared docs project-neutral Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Radoslav Dimitrov --- .../skills/respond-to-rfc-comments/SKILL.md | 4 ++-- .claude/skills/review-rfc/SKILL.md | 2 +- .claude/skills/write-rfc/SKILL.md | 2 +- .../workflows/validate-proposal-naming.yml | 6 +++--- CONTRIBUTING.md | 12 ++++++------ README.md | 19 ++++++++++--------- SECURITY.md | 10 +++++----- toolhive/AGENTS.md | 7 ++++--- ...047-vmcp-proxyrunner-horizontal-scaling.md | 6 +++--- toolhive/THV-0059-vmcp-local-experience.md | 10 +++++----- 10 files changed, 40 insertions(+), 38 deletions(-) diff --git a/.claude/skills/respond-to-rfc-comments/SKILL.md b/.claude/skills/respond-to-rfc-comments/SKILL.md index 2460094..929af71 100644 --- a/.claude/skills/respond-to-rfc-comments/SKILL.md +++ b/.claude/skills/respond-to-rfc-comments/SKILL.md @@ -1,6 +1,6 @@ --- name: respond-to-rfc-comments -description: Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for any project in this repository (toolhive, mecatl, ...). +description: Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for any project in this repository (toolhive, mecatl, ...), including the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard repositories. allowed-tools: Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Edit, Write, AskUserQuestion --- @@ -85,7 +85,7 @@ After replies are posted, ask the user if they want to commit and push. If confi - When renaming fields or terms, use `replace_all` to catch every occurrence. - When adding new sections, match the style of existing sections in the RFC. - When adding sections required by the template (e.g., Security Considerations), reference existing RFCs in the repo for structural patterns: - - Search for the section name across `/*.md` files. + - Search for the section name across `/-*.md` files. - Use 2-3 examples to match the established format (threat model tables, subsection structure, etc.). ### PR-Level Comment Responses diff --git a/.claude/skills/review-rfc/SKILL.md b/.claude/skills/review-rfc/SKILL.md index fd8f7b2..287a9ea 100644 --- a/.claude/skills/review-rfc/SKILL.md +++ b/.claude/skills/review-rfc/SKILL.md @@ -175,4 +175,4 @@ Structure your review as follows: - Project rules: `/AGENTS.md` - Template: `template.md` - Contributing guide: `CONTRIBUTING.md` -- Existing RFCs: `/*.md` +- Existing RFCs: `/-*.md` diff --git a/.claude/skills/write-rfc/SKILL.md b/.claude/skills/write-rfc/SKILL.md index e04b963..0817038 100644 --- a/.claude/skills/write-rfc/SKILL.md +++ b/.claude/skills/write-rfc/SKILL.md @@ -111,4 +111,4 @@ Before finalizing, verify: - Project rules: `/AGENTS.md` - Template: `template.md` - Contributing guide: `CONTRIBUTING.md` -- Existing RFCs: `/*.md` +- Existing RFCs: `/-*.md` diff --git a/.github/workflows/validate-proposal-naming.yml b/.github/workflows/validate-proposal-naming.yml index bc36d46..8874aae 100644 --- a/.github/workflows/validate-proposal-naming.yml +++ b/.github/workflows/validate-proposal-naming.yml @@ -32,7 +32,7 @@ jobs: echo "Using PR number from manual input: $(printf %04d ${{ inputs.pr_number }})" else echo "PR_NUMBER=$(printf %04d ${{ github.event.number }})" >> $GITHUB_ENV - echo "Using PR number from event: $(printf %04d ${{ inputs.pr_number }})" + echo "Using PR number from event: $(printf %04d ${{ github.event.number }})" fi - name: Validate proposal naming @@ -44,8 +44,8 @@ jobs: ) # Get the list of NEW files added in a project folder (not modifications to existing files). - # Only top-level project folders are considered; READMEs are not RFCs. - CHANGED_FILES=$(git diff --name-only --diff-filter=A origin/${{ github.base_ref }}...HEAD | grep -E '^[^./][^/]*/[^/]+\.md$' | grep -vE '/README\.md$' || true) + # Only top-level project folders are considered; README.md, AGENTS.md and CLAUDE.md are not RFCs. + CHANGED_FILES=$(git diff --name-only --diff-filter=A origin/${{ github.base_ref }}...HEAD | grep -E '^[^./][^/]*/[^/]+\.md$' | grep -vE '/(README|AGENTS|CLAUDE)\.md$' || true) # Skip validation if no new proposal files are being added # (modifications to existing proposals don't need naming validation) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae58f90..541bbaa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to Stacklok RFCs -First off, thank you for taking the time to contribute to ToolHive! :+1: :tada: -ToolHive is released under the Apache 2.0 license. If you would like to +First off, thank you for taking the time to contribute to Stacklok projects! :+1: :tada: +This repository is released under the Apache 2.0 license. If you would like to contribute an RFC or want to participate in the design process, this document should help you get started. @@ -27,7 +27,7 @@ report unacceptable behavior to ## Reporting security vulnerabilities -If you think you have found a security vulnerability in any ToolHive project, +If you think you have found a security vulnerability in any Stacklok project, please DO NOT disclose it publicly until we've had a chance to fix it. Please don't report security vulnerabilities using GitHub issues; instead, please follow this @@ -48,8 +48,8 @@ RFC, start a thread first. GitHub Issues in this repository are used to track RFC status and any meta-discussions about the RFC process itself. -For general usage questions about ToolHive, please ask in -[ToolHive's discussion forum](https://discord.gg/stacklok). +For general usage questions about our projects, please ask in +[our discussion forum](https://discord.gg/stacklok). ### Not sure how to start contributing? @@ -68,7 +68,7 @@ If you're new to the RFC process: - Fork this repository to your own GitHub account - Copy `template.md` to `/-XXXX-descriptive-name.md` (e.g. `toolhive/THV-XXXX-descriptive-name.md`) - - Use the next available RFC number (check existing RFCs) + - Keep `XXXX` as a placeholder while drafting, then rename the file to your PR number once the PR is open - Fill in all required sections of the template 3. **Submit a Pull Request**: diff --git a/README.md b/README.md index baaafd0..a4eeac2 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ You should write an RFC for: - Significant architectural changes - Changes that affect the public API or user-facing behavior - Security-sensitive changes -- Cross-cutting concerns that span multiple ToolHive projects +- Cross-cutting concerns that span multiple projects or repositories - Breaking changes or deprecations You probably **don't** need an RFC for: @@ -31,8 +31,8 @@ Each project has its own folder, filename prefix and `AGENTS.md` describing its | Project | Folder | Prefix | |---------|--------|--------| -| ToolHive ecosystem | [`toolhive/`](toolhive/AGENTS.md) | `THV-` | -| Mecatl | [`mecatl/`](mecatl/AGENTS.md) | `MEC-` | +| ToolHive ecosystem | [`toolhive/`](toolhive/AGENTS.md) | `THV` | +| Mecatl | [`mecatl/`](mecatl/AGENTS.md) | `MEC` | To onboard a new project, see [Adding a project](AGENTS.md#adding-a-project) in the root `AGENTS.md`. @@ -46,7 +46,7 @@ Before writing a full RFC, consider opening a thread on [Discord](https://discor 1. Fork this repository 2. Copy `template.md` to `/-XXXX-descriptive-name.md` (e.g. `toolhive/THV-XXXX-descriptive-name.md`) - - Use the next available Pull Request number for your RFC (check existing RFCs) + - Keep `XXXX` as a placeholder while drafting, then rename the file to the number of your Pull Request once it is open - Use a short, descriptive name with hyphens 3. Fill in the RFC template 4. Submit a Pull Request @@ -63,8 +63,8 @@ Before writing a full RFC, consider opening a thread on [Discord](https://discor RFCs can be: - **Accepted**: The RFC is approved and can be implemented - **Rejected**: The RFC is not approved (with explanation) -- **Postponed**: The RFC is deferred for future consideration -- **Withdrawn**: The author withdraws the RFC +- **Superseded**: A newer RFC replaces it +- **Implemented**: The accepted RFC has been implemented ### 5. Implementation @@ -75,7 +75,7 @@ Once accepted, the RFC can be implemented. The RFC should be updated with: ## RFC Numbering -RFCs are numbered based on the PR numbers, so they are incremental, but not necessarily sequential (0001, 0002, 0004, etc.). The number sequence is shared across all projects; only the prefix differs. When creating a new RFC, check the existing RFCs and use the next available number. A CI task will ensure you're using the right number. +RFCs are numbered based on the PR numbers, so they are incremental, but not necessarily sequential (0001, 0002, 0004, etc.). The number sequence is shared across all projects; only the prefix differs. Draft with `XXXX` and rename the file to your PR number once the PR is open. A CI task will ensure you're using the right number. For RFCs that originate from issues in specific repositories, you may reference the issue number in the RFC (e.g., "This RFC addresses toolhive#1234"). @@ -90,8 +90,9 @@ rfcs/ ├── toolhive/ # One folder per project │ ├── AGENTS.md # Project scope, repositories and conventions │ └── THV-XXXX-*.md # RFCs, prefixed per project -└── assets/ # Images and diagrams for RFCs - └── XXXX/ # Assets for RFC XXXX +└── mecatl/ + ├── AGENTS.md + └── MEC-XXXX-*.md ``` ## License diff --git a/SECURITY.md b/SECURITY.md index 7c8c729..b704f4e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,16 +1,16 @@ # Security Policy -The ToolHive community takes security seriously! We appreciate your efforts to +The Stacklok community takes security seriously! We appreciate your efforts to disclose your findings responsibly and will make every effort to acknowledge your contributions. ## Scope This repository contains RFCs (Request for Comments) and design documents for -the ToolHive ecosystem. While RFCs themselves do not contain executable code, +the Stacklok ecosystem. While RFCs themselves do not contain executable code, security considerations in RFC designs are important. -For security vulnerabilities in ToolHive implementations, please report them to +For security vulnerabilities in project implementations, please report them to the appropriate repository: - [ToolHive CLI](https://github.com/stacklok/toolhive/security/advisories/new) @@ -33,7 +33,7 @@ Include: - Potential impact if the design is implemented as-is - Suggested mitigations or design changes -### Contacting the ToolHive security team +### Contacting the Stacklok security team Contact the team by sending email to [security@stacklok.com](mailto:security@stacklok.com). @@ -42,7 +42,7 @@ Contact the team by sending email to ### Private disclosure processes -The ToolHive community asks that all suspected vulnerabilities be handled in +The Stacklok community asks that all suspected vulnerabilities be handled in accordance with the [Responsible Disclosure model](https://en.wikipedia.org/wiki/Responsible_disclosure). diff --git a/toolhive/AGENTS.md b/toolhive/AGENTS.md index c4be1df..ee26434 100644 --- a/toolhive/AGENTS.md +++ b/toolhive/AGENTS.md @@ -65,12 +65,13 @@ Transport types: **stdio** (needs protocol translation), **SSE** and **streamabl 1. **Platform, not runner**: enhances the platform abstraction. 2. **Security by default**: maintains or improves the security posture. 3. **Middleware composability**: implemented as middleware where appropriate. -4. **RunConfig portability**: keeps configuration portable (RunConfig is the portable API contract). -5. **Cloud-native**: Kubernetes-friendly where applicable. +4. **Extensibility**: new cross-cutting behavior fits the middleware model. +5. **RunConfig portability**: keeps configuration portable (RunConfig is the portable API contract). +6. **Cloud-native**: Kubernetes-friendly where applicable. ## Conventions - Code examples: **Go** for toolhive and toolhive-registry-server, **TypeScript** for toolhive-studio and toolhive-cloud-ui, **YAML** for configuration. -- Kubernetes RFCs include CRD examples (`apiVersion: toolhive.stacklok.dev/v1alpha1`). CRD types: `MCPServer`, `MCPRegistry`, `MCPToolConfig`, `MCPExternalAuthConfig`, `MCPGroup`, `VirtualMCPServer`. Follow Kubernetes API conventions. +- Kubernetes RFCs include CRD examples (`apiVersion: toolhive.stacklok.dev/v1alpha1`). CRD types: `MCPServer` (individual server deployment), `MCPRegistry` (registry configuration), `MCPToolConfig` (tool filtering and configuration), `MCPExternalAuthConfig` (external authentication), `MCPGroup` (server grouping), `VirtualMCPServer` (aggregation of multiple servers). Follow Kubernetes API conventions. - Use ToolHive terminology correctly (Workloads, Transports, Middleware, RunConfig, ...). - API and configuration designs stay consistent with existing APIs and RunConfig patterns in the target repository. diff --git a/toolhive/THV-0047-vmcp-proxyrunner-horizontal-scaling.md b/toolhive/THV-0047-vmcp-proxyrunner-horizontal-scaling.md index 3d18a0d..7b05bb1 100644 --- a/toolhive/THV-0047-vmcp-proxyrunner-horizontal-scaling.md +++ b/toolhive/THV-0047-vmcp-proxyrunner-horizontal-scaling.md @@ -8,7 +8,7 @@ - **Related Issues**: - [toolhive#3986](https://github.com/stacklok/toolhive/pull/3986) - Enable sticky sessions on operator-created Services - [toolhive#3992](https://github.com/stacklok/toolhive/pull/3992) - Add ClusterIP service with SessionAffinity for MCP server backend - - [THV-0038](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0038-session-scoped-client-lifecycle.md) - Session-Scoped Client Lifecycle for vMCP + - [THV-0038](THV-0038-session-scoped-client-lifecycle.md) - Session-Scoped Client Lifecycle for vMCP - [toolhive#1589](https://github.com/stacklok/toolhive/issues/1589) - Scaling stdio within k8s. ## Summary @@ -76,7 +76,7 @@ Today, only `LocalStorage` (in-process memory map) is implemented. The `Storage` #### vMCP Session-Scoped Architecture (THV-0038) -[THV-0038](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0038-session-scoped-client-lifecycle.md) refactored vMCP's session management to introduce explicit session lifecycle: backend HTTP clients are created once at session initialization, reused for all requests within the session, and closed on expiry. The resulting `MultiSession` interface owns the routing table for that session (which tool belongs to which backend), as well as live backend connections. +[THV-0038](THV-0038-session-scoped-client-lifecycle.md) refactored vMCP's session management to introduce explicit session lifecycle: backend HTTP clients are created once at session initialization, reused for all requests within the session, and closed on expiry. The resulting `MultiSession` interface owns the routing table for that session (which tool belongs to which backend), as well as live backend connections. The `session.go` documentation in the codebase is explicit about the distributed scaling trade-off: @@ -194,7 +194,7 @@ For `SSE` and `streamable-http`, the session exists as a logical identifier (`Mc - **`stdio` transport scaling**: The proxyrunner's attachment to the MCP container's stdin/stdout is inherently single-process. Horizontal scaling of stdio-backed servers requires re-initializing the container session and is out of scope for this RFC. - **Smart Routing at vMCP**: We've previously discussed having vMCP route requests to the same underlying proxyrunner that's previously serviced the session. While this may be useful long term to reduce Redis load and reduce latency, it's not strictly necessary in the short term. vMCP will continue to send requests through k8s Service associated with the proxyrunner. - **One StatefulSet per MCPServer (shared)**: The design maintains exactly one StatefulSet per `MCPServer`. All proxyrunner replicas for a given `MCPServer` share that single StatefulSet, converging on the same spec via server-side apply. Each proxyrunner replica routes its sessions to specific pods within the shared StatefulSet. Note: a 1:1 ratio (one StatefulSet per proxyrunner replica) could be a future direction if enabling `stdio` horizontal scaling were desired, since each proxyrunner would then have its own dedicated backend. -- **Moving MCP server deployment out of the proxyrunner**: The proxyrunner remains responsible for creating, managing, and proxying to the MCP server StatefulSet. Changing this responsibility boundary (e.g., having vMCP manage backends directly) is desirable long-term but is more work and out of scope. Discussed in detail [here](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0003-toolhive-kubernetes-architecture-improvement.md). +- **Moving MCP server deployment out of the proxyrunner**: The proxyrunner remains responsible for creating, managing, and proxying to the MCP server StatefulSet. Changing this responsibility boundary (e.g., having vMCP manage backends directly) is desirable long-term but is more work and out of scope. Discussed in detail [here](THV-0003-toolhive-kubernetes-architecture-improvement.md). - **Auto-scaling policy**: How to trigger scale-out (HPA metrics, KEDA event sources, custom metrics) is deferred to a follow-on RFC. This RFC makes auto-scaling possible; it does not specify when or how to do it. - **Backend StatefulSet scale-in**: Removing pods from the `MCPServer` StatefulSet (reducing `spec.backendReplicas`) is always disruptive — the backend session state lives in the removed process and cannot be reconstructed. Graceful drain of backend pods is out of scope for this RFC. - **Scalable SSE elicitation and sampling**: Both SSE and Streamable HTTP transports can use server-sent event streams to deliver server-to-client requests (elicitation, sampling) mid-flight. These long-lived streams are pinned to a specific pod, so scaling them would require intra-deployment routing to forward client response POSTs to the pod holding the open stream. This adds significant complexity for a pattern most deployments do not use. The MCP spec is evolving toward stateless-friendly alternatives (tasks, reconnectable streams) that may mitigate this; until then, we flag it as a known gap and candidate for future work. diff --git a/toolhive/THV-0059-vmcp-local-experience.md b/toolhive/THV-0059-vmcp-local-experience.md index bfcad13..229085c 100644 --- a/toolhive/THV-0059-vmcp-local-experience.md +++ b/toolhive/THV-0059-vmcp-local-experience.md @@ -849,11 +849,11 @@ The `thv vmcp` subcommand introduces no new attack surface beyond what the stand ## References -- [THV-0022: Optimizer Migration to vMCP](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0022-optimizer-migration-to-vmcp.md) — Optimizer architecture (SQLite FTS5, TEI embeddings, session-scoped indexing) -- [THV-0008: Virtual MCP Server](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0008-virtual-mcp-server.md) — Original vMCP design -- [THV-0014: K8s-Aware vMCP with Dynamic Backend Discovery](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0014-vmcp-k8s-aware-refactor.md) — K8s discovery mode -- [THV-0034: Local Long-Running Server Architecture](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0034-long-running-local-server.md) — Future integration point -- [THV-0047: vMCP/ProxyRunner Horizontal Scaling](https://github.com/stacklok/toolhive-rfcs/blob/main/rfcs/THV-0047-vmcp-proxyrunner-horizontal-scaling.md) — Scaling considerations +- [THV-0022: Optimizer Migration to vMCP](THV-0022-optimizer-migration-to-vmcp.md) — Optimizer architecture (SQLite FTS5, TEI embeddings, session-scoped indexing) +- [THV-0008: Virtual MCP Server](THV-0008-virtual-mcp-server.md) — Original vMCP design +- [THV-0014: K8s-Aware vMCP with Dynamic Backend Discovery](THV-0014-vmcp-k8s-aware-refactor.md) — K8s discovery mode +- [THV-0034: Local Long-Running Server Architecture](THV-0034-long-running-local-server.md) — Future integration point +- [THV-0047: vMCP/ProxyRunner Horizontal Scaling](THV-0047-vmcp-proxyrunner-horizontal-scaling.md) — Scaling considerations - [brood-box vMCP integration](https://github.com/stacklok/brood-box/tree/main/internal/infra/mcp) — Reference implementation of library embedding pattern - [ToolHive vMCP architecture docs](https://github.com/stacklok/toolhive/blob/main/docs/arch/10-virtual-mcp-architecture.md) — Architecture documentation - [vMCP package documentation](https://github.com/stacklok/toolhive/blob/main/pkg/vmcp/doc.go) — Package-level docs