From 509ff7574a19f1f819dc75d2d604ed71d29035dd Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Wed, 1 Jul 2026 03:46:45 -0400 Subject: [PATCH 1/2] docs: Document MCP security model and trust boundaries for #52 --- docs/credential-isolation.md | 9 +++++++++ docs/release-workflows.md | 9 +++++++++ docs/safety-model.md | 15 +++++++++++++++ docs/tool-boundaries.md | 11 +++++++++++ 4 files changed, 44 insertions(+) create mode 100644 docs/credential-isolation.md create mode 100644 docs/release-workflows.md create mode 100644 docs/safety-model.md create mode 100644 docs/tool-boundaries.md diff --git a/docs/credential-isolation.md b/docs/credential-isolation.md new file mode 100644 index 0000000..a194010 --- /dev/null +++ b/docs/credential-isolation.md @@ -0,0 +1,9 @@ +# Credential Isolation + +This document describes how credentials and sensitive environment variables are handled within the MCP tools monorepo. + +## Separate Credentials +Even though multiple MCP servers share the same monorepo, they **must** have separate credentials and runtimes. + +- **No Shared Environments**: Each MCP server (`gitea-mcp`, `jenkins-mcp`, `ops-mcp`, etc.) must be instantiated as an independent service with its own dedicated `.env` configuration file. +- **Strict Isolation**: A server will only have access to the credentials required for its specific trust boundary. For instance, `gitea-mcp` has no access to Jenkins or Ops authentication tokens. diff --git a/docs/release-workflows.md b/docs/release-workflows.md new file mode 100644 index 0000000..c2d3fc5 --- /dev/null +++ b/docs/release-workflows.md @@ -0,0 +1,9 @@ +# Release Workflows + +This document outlines the scope and boundaries of the optional future `release-mcp` orchestrator. + +## Orchestrator Role +The `release-mcp` package may be introduced later to coordinate workflows across the different MCP packages. + +- **Coordination, not Consolidation**: It can call or compose other tools, but it **must not** become an all-powerful server holding credentials for all other components. +- **Example Workflows**: Tasks such as collecting release evidence, verifying TEST deploy checklists, summarizing state (issue/PR/build/deploy), and posting evidence back to Gitea. diff --git a/docs/safety-model.md b/docs/safety-model.md new file mode 100644 index 0000000..bcc92a4 --- /dev/null +++ b/docs/safety-model.md @@ -0,0 +1,15 @@ +# MCP Safety Model + +This document outlines the safety requirements for all tools within the MCP monorepo. + +## 1. Audit Logging and Confirmation +All mutating actions (e.g., triggering builds, creating resources, updating environments) must be recorded in an audit log. These actions require explicit confirmation from the user before execution to prevent accidental state changes. + +## 2. Production Environment Safety +Any action that targets a production environment must have a hard confirmation gate. Production actions must never run based on vague or ambiguous prompts. The user must provide explicit, unambiguous consent to proceed with a production deployment or modification. + +## 3. Secret Redaction +To maintain a secure environment, all secrets, tokens, passwords, and sensitive keys must be strictly redacted from: +- System and application logs +- Tool return values/outputs +- Any form of persistent storage or console output diff --git a/docs/tool-boundaries.md b/docs/tool-boundaries.md new file mode 100644 index 0000000..db75e4a --- /dev/null +++ b/docs/tool-boundaries.md @@ -0,0 +1,11 @@ +# Tool Boundaries + +This document defines the strict boundaries between the different MCP server packages within the monorepo. + +## 1. Architectural Philosophy +- **One MCP Server per Trust Boundary**: While the packages share a monorepo, their runtime services must remain entirely separate. There is no single "everything" server. + +## 2. Package-Specific Boundaries +- **gitea-mcp**: Restricted to source-control and work-item capabilities (issues, PRs, comments). This package **must not** have Jenkins or Ops credentials, nor can it execute deploy operations. +- **jenkins-mcp**: Focused on CI/CD capabilities. This package **must not** have Ops credentials unless explicitly configured for a specific, isolated pipeline later. +- **ops-mcp**: Dedicated to live environment and host checks. In its initial state, this package starts as strictly read-only (e.g., health checks, status checks, log reading). -- 2.43.7 From b402de83feeec0353728893ef0ff43f51554cff8 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Wed, 1 Jul 2026 04:17:30 -0400 Subject: [PATCH 2/2] docs: fix trailing whitespace and add approved naming for #52 Address reviewer blockers on PR #8: - Remove trailing whitespace in credential-isolation.md and release-workflows.md - Add approved naming coverage (MCP Control Plane / mcp-control-plane project and repo names; common, gitea-mcp, jenkins-mcp, ops-mcp, release-mcp packages) to tool-boundaries.md Documentation-only. No code, scaffolding, or config changes. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/credential-isolation.md | 2 +- docs/release-workflows.md | 2 +- docs/tool-boundaries.md | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/credential-isolation.md b/docs/credential-isolation.md index a194010..e8b34b8 100644 --- a/docs/credential-isolation.md +++ b/docs/credential-isolation.md @@ -3,7 +3,7 @@ This document describes how credentials and sensitive environment variables are handled within the MCP tools monorepo. ## Separate Credentials -Even though multiple MCP servers share the same monorepo, they **must** have separate credentials and runtimes. +Even though multiple MCP servers share the same monorepo, they **must** have separate credentials and runtimes. - **No Shared Environments**: Each MCP server (`gitea-mcp`, `jenkins-mcp`, `ops-mcp`, etc.) must be instantiated as an independent service with its own dedicated `.env` configuration file. - **Strict Isolation**: A server will only have access to the credentials required for its specific trust boundary. For instance, `gitea-mcp` has no access to Jenkins or Ops authentication tokens. diff --git a/docs/release-workflows.md b/docs/release-workflows.md index c2d3fc5..5efadcf 100644 --- a/docs/release-workflows.md +++ b/docs/release-workflows.md @@ -5,5 +5,5 @@ This document outlines the scope and boundaries of the optional future `release- ## Orchestrator Role The `release-mcp` package may be introduced later to coordinate workflows across the different MCP packages. -- **Coordination, not Consolidation**: It can call or compose other tools, but it **must not** become an all-powerful server holding credentials for all other components. +- **Coordination, not Consolidation**: It can call or compose other tools, but it **must not** become an all-powerful server holding credentials for all other components. - **Example Workflows**: Tasks such as collecting release evidence, verifying TEST deploy checklists, summarizing state (issue/PR/build/deploy), and posting evidence back to Gitea. diff --git a/docs/tool-boundaries.md b/docs/tool-boundaries.md index db75e4a..d5c29cd 100644 --- a/docs/tool-boundaries.md +++ b/docs/tool-boundaries.md @@ -2,6 +2,8 @@ This document defines the strict boundaries between the different MCP server packages within the monorepo. +The project is named **MCP Control Plane** and lives in the `mcp-control-plane` repository. It groups the following packages: `common`, `gitea-mcp`, `jenkins-mcp`, `ops-mcp`, and `release-mcp`. + ## 1. Architectural Philosophy - **One MCP Server per Trust Boundary**: While the packages share a monorepo, their runtime services must remain entirely separate. There is no single "everything" server. -- 2.43.7