From ef239e6e89767469085455201d5a98cc20e2f6d1 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Tue, 24 Feb 2026 11:11:02 -0500 Subject: [PATCH 1/2] chore: add repository-specific copilot instructions --- .github/copilot-instructions.md | 149 ++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..f725f04 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,149 @@ +# capiscio-mcp-python - GitHub Copilot Instructions + +## ⛔ ABSOLUTE RULES - NO EXCEPTIONS + +### 1. ALL WORK VIA PULL REQUESTS +- **NEVER commit directly to `main`.** All changes MUST go through PRs. +- Create feature branches: `feature/`, `fix/`, `chore/` + +### 2. RUN TESTS LOCALLY BEFORE PUSH +- `pytest -v` must pass before pushing + +### 3. NO WATCH/BLOCKING COMMANDS +- **NEVER run blocking commands** without timeout + +--- + +## 🚨 CRITICAL: Read First + +**Before starting work, read the workspace context files:** +1. `../../.context/CURRENT_SPRINT.md` +2. `../../.context/ACTIVE_TASKS.md` +3. `../../.context/SESSION_LOG.md` + +--- + +## Repository Purpose + +**capiscio-mcp-python** (PyPI: `capiscio-mcp`) is the MCP Guard — tool-level security for Model Context Protocol servers. It implements: + +- **RFC-006**: MCP Tool Authority and Evidence +- **RFC-007**: MCP Server Identity Disclosure and Verification + +**Current Version**: v2.4.0 + +## Architecture + +``` +capiscio-mcp-python/ +├── capiscio_mcp/ +│ ├── __init__.py # Public API exports +│ ├── guard.py # @guard decorator — core trust enforcement +│ ├── evidence.py # Cryptographic audit trail logging +│ ├── server_identity.py # Server DID generation & registration +│ ├── verify.py # Badge verification (calls capiscio-core gRPC) +│ ├── fastmcp.py # FastMCP integration wrapper +│ └── types.py # Shared type definitions +├── docs/ # MkDocs documentation +├── tests/ # Test suite +└── pyproject.toml # Package configuration +``` + +## Key Concepts + +### @guard Decorator + +The primary API surface. Wraps MCP tool handlers with trust-level enforcement: + +```python +from capiscio_mcp import guard + +@guard(min_trust_level=2) +async def sensitive_tool(query: str, badge: str) -> str: + """Only agents with trust level ≥ 2 can call this.""" + ... +``` + +### FastMCP Integration + +For use with the MCP SDK's FastMCP server: + +```python +from capiscio_mcp.fastmcp import GuardedMCP + +mcp = GuardedMCP("my-server", default_trust_level=1) + +@mcp.tool() +@guard(min_trust_level=2) +async def protected_tool(query: str) -> str: + ... +``` + +### Server Identity + +MCP servers register their own identity (DID) with CapiscIO: + +```python +from capiscio_mcp import register_server, verify_server + +# Register this server's identity +identity = await register_server(name="my-mcp-server", url="https://...") + +# Verify another server +result = await verify_server("did:web:other-server.example.com") +``` + +### Evidence Logging + +Every guarded tool call produces a cryptographic evidence record: + +```python +# Evidence is automatically collected by @guard +# Contains: caller DID, tool name, timestamp, badge JTI, trust level +``` + +## Critical Rules + +### 1. RFC Compliance +- RFC-006 defines the evidence format — don't change the schema +- RFC-007 defines server identity — follow the DID document structure + +### 2. gRPC Dependency +Badge verification calls capiscio-core via gRPC. The `CAPISCIO_CORE_ADDR` environment variable must point to the core service: +```bash +CAPISCIO_CORE_ADDR=localhost:50051 # Local development +``` + +### 3. Trust Level Semantics +- Level 0: Self-signed (no verification) +- Level 1: Domain validated (DV) +- Level 2: Organization validated (OV) +- Level 3: Extended validated (EV) +- Level 4: Reserved (not yet implemented) + +### 4. Async-First +All public APIs are async. Do NOT add synchronous wrappers without discussion. + +## Environment Variables + +```bash +CAPISCIO_CORE_ADDR=localhost:50051 # gRPC address for capiscio-core +CAPISCIO_SERVER_URL=https://registry.capisc.io # Registry URL +CAPISCIO_LOG_LEVEL=info # Logging level +``` + +## Common Commands + +```bash +# Install for development +pip install -e ".[dev,mcp]" + +# Run tests +pytest -v + +# Build docs +mkdocs serve + +# Type checking +mypy capiscio_mcp/ +``` From 577ced972dabcb4ac1218aeba738882d4d48766d Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Tue, 24 Feb 2026 12:51:15 -0500 Subject: [PATCH 2/2] fix: address all PR review documentation issues - Remove references to external .context/ files - Fix architecture tree to match actual module structure - Update integration example to use CapiscioMCPServer - Fix API function names (setup_server_identity, register_server_identity) - Correct environment variables (remove non-existent CAPISCIO_SERVER_URL, CAPISCIO_LOG_LEVEL) - Change mkdocs serve to mkdocs build (avoid blocking command) - Clarify CAPISCIO_CORE_ADDR is optional with auto-start - Update async APIs statement to reflect sync wrapper existence --- .github/copilot-instructions.md | 51 +++++++++++++++++++-------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f725f04..a389e39 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -16,10 +16,7 @@ ## 🚨 CRITICAL: Read First -**Before starting work, read the workspace context files:** -1. `../../.context/CURRENT_SPRINT.md` -2. `../../.context/ACTIVE_TASKS.md` -3. `../../.context/SESSION_LOG.md` +**Before starting work, check the repo's README.md and existing code patterns.** --- @@ -39,11 +36,13 @@ capiscio-mcp-python/ ├── capiscio_mcp/ │ ├── __init__.py # Public API exports │ ├── guard.py # @guard decorator — core trust enforcement -│ ├── evidence.py # Cryptographic audit trail logging -│ ├── server_identity.py # Server DID generation & registration -│ ├── verify.py # Badge verification (calls capiscio-core gRPC) -│ ├── fastmcp.py # FastMCP integration wrapper -│ └── types.py # Shared type definitions +│ ├── server.py # Server verification utilities +│ ├── registration.py # Server DID generation & registration +│ ├── pop.py # Proof-of-possession and evidence handling +│ ├── integrations/ # MCP framework integrations +│ │ └── mcp.py # CapiscioMCPServer/Client wrappers +│ ├── types.py # Shared type definitions +│ └── errors.py # Error classes ├── docs/ # MkDocs documentation ├── tests/ # Test suite └── pyproject.toml # Package configuration @@ -69,11 +68,11 @@ async def sensitive_tool(query: str, badge: str) -> str: For use with the MCP SDK's FastMCP server: ```python -from capiscio_mcp.fastmcp import GuardedMCP +from capiscio_mcp.integrations.mcp import CapiscioMCPServer -mcp = GuardedMCP("my-server", default_trust_level=1) +server = CapiscioMCPServer("my-server", default_trust_level=1) -@mcp.tool() +@server.tool() @guard(min_trust_level=2) async def protected_tool(query: str) -> str: ... @@ -84,10 +83,13 @@ async def protected_tool(query: str) -> str: MCP servers register their own identity (DID) with CapiscIO: ```python -from capiscio_mcp import register_server, verify_server +from capiscio_mcp import setup_server_identity, register_server_identity, verify_server -# Register this server's identity -identity = await register_server(name="my-mcp-server", url="https://...") +# Set up this server's identity (generates keys, prepares DID document) +await setup_server_identity(name="my-mcp-server", url="https://...") + +# Register this server's identity with the CapiscIO registry +identity = await register_server_identity() # Verify another server result = await verify_server("did:web:other-server.example.com") @@ -121,15 +123,22 @@ CAPISCIO_CORE_ADDR=localhost:50051 # Local development - Level 3: Extended validated (EV) - Level 4: Reserved (not yet implemented) -### 4. Async-First -All public APIs are async. Do NOT add synchronous wrappers without discussion. +### 4. Async-First APIs +Public APIs are **async-first** — prefer async interfaces. Synchronous wrappers (e.g., `*_sync`) exist for compatibility; do not add new sync wrappers or change existing ones without discussion and clear documentation. ## Environment Variables ```bash -CAPISCIO_CORE_ADDR=localhost:50051 # gRPC address for capiscio-core -CAPISCIO_SERVER_URL=https://registry.capisc.io # Registry URL -CAPISCIO_LOG_LEVEL=info # Logging level +# Optional: Point to a running capiscio-core gRPC server (default: auto-start local) +CAPISCIO_CORE_ADDR=localhost:50051 + +# Optional: Filesystem path to capiscio-core binary +CAPISCIO_BINARY_PATH=/path/to/capiscio-core +# or set CAPISCIO_BINARY if the binary is on your PATH: +# CAPISCIO_BINARY=capiscio-core + +# Server origin for evidence logging +CAPISCIO_SERVER_ORIGIN=http://localhost:8000 ``` ## Common Commands @@ -142,7 +151,7 @@ pip install -e ".[dev,mcp]" pytest -v # Build docs -mkdocs serve +mkdocs build # Type checking mypy capiscio_mcp/