From ba0ec1b7b5db41d20718e45c2f948b7367bc9eba Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Tue, 12 May 2026 01:56:45 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20polish=20README=20for=20PyCon=20?= =?UTF-8?q?=E2=80=94=20fix=20examples,=20add=20quickstart=20nav,=20ecosyst?= =?UTF-8?q?em=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 251eb6b..8a7def0 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# CapiscIO MCP Guard +# MCP Guard -Tool-level security for Model Context Protocol servers. +Tool-level trust enforcement for Model Context Protocol servers. [![PyPI version](https://badge.fury.io/py/capiscio-mcp.svg)](https://badge.fury.io/py/capiscio-mcp) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -**MCP Guard** provides trust badges and identity verification for [Model Context Protocol (MCP)](https://modelcontextprotocol.io) tool calls. It implements: +**MCP Guard** (`pip install capiscio-mcp`) provides trust badges and identity verification for [Model Context Protocol (MCP)](https://modelcontextprotocol.io) tool calls. It implements: - **RFC-006**: MCP Tool Authority and Evidence - **RFC-007**: MCP Server Identity Disclosure and Verification @@ -41,6 +41,12 @@ MCP Guard solves this with: | **Server registration** | Generate keypairs and register server DIDs | | **Trust levels** | 0 (self-signed) → 4 (extended validation) | +## Quickstarts + +> **Building an MCP server?** Start with [Quickstart 1](#quickstart-1-server-side-tool-guarding). +> **Connecting to MCP servers?** Start with [Quickstart 2](#quickstart-2-client-side-server-verification). +> **Registering a server identity?** Start with [Quickstart 3](#quickstart-3-server-registration). + ## Quickstart 1: Server-Side (Tool Guarding) Protect your MCP tools with trust-level requirements: @@ -160,16 +166,14 @@ server = CapiscioMCPServer( ) @server.tool(min_trust_level=2) -async def read_file(path: str) -> str: - """Only agents with Trust Level 2+ can read files.""" - with open(path) as f: - return f.read() +async def execute_query(sql: str) -> list[dict]: + """Only agents with Trust Level 2+ can query the database.""" + return await db.fetch_all(sql) @server.tool(min_trust_level=0) -async def list_files(directory: str) -> list[str]: - """Any authenticated agent can list files.""" - import os - return os.listdir(directory) +async def list_tables() -> list[str]: + """Any authenticated agent can list available tables.""" + return await db.get_table_names() # Run the server (stdio transport) server.run() @@ -458,6 +462,16 @@ mypy capiscio_mcp ruff check capiscio_mcp ``` +## Related Packages + +| Package | What it does | Install | +|---------|-------------|---------| +| [Agent Guard](https://github.com/capiscio/capiscio-sdk-python) | Runtime trust verification for A2A agents | `pip install capiscio-sdk` | +| [CapiscIO CLI](https://github.com/capiscio/capiscio-python) | Agent validation for CI/CD pipelines | `pip install capiscio` | +| [capiscio-core](https://github.com/capiscio/capiscio-core) | Go library, CLI binary, and gateway | `go install` | + +[Documentation](https://docs.capisc.io) · [Website](https://capisc.io) · [Platform](https://app.capisc.io) + ## License Apache License 2.0 From 82b916257d6aa4fdf2d69c9b93f3ff24404ff861 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Wed, 13 May 2026 09:58:57 -0400 Subject: [PATCH 2/2] docs: address review comments on README examples - Replace raw SQL execute_query() with parameterized get_user() - Bump list_tables to trust level 1, fix wording to avoid implying level 0 means authenticated - Add db placeholder initialization comment - Replace bare 'go install' with link to install guide --- README.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 8a7def0..a6c7d25 100644 --- a/README.md +++ b/README.md @@ -159,20 +159,23 @@ Create an MCP server with built-in trust enforcement: ```python from capiscio_mcp.integrations.mcp import CapiscioMCPServer +# db is your application's database connection (asyncpg, databases, etc.) +db = ... # e.g. databases.Database("postgresql://...") + server = CapiscioMCPServer( - name="filesystem", - did="did:web:mcp.example.com:servers:filesystem", + name="data-api", + did="did:web:mcp.example.com:servers:data-api", badge="eyJhbGc...", # From CapiscIO registry ) @server.tool(min_trust_level=2) -async def execute_query(sql: str) -> list[dict]: - """Only agents with Trust Level 2+ can query the database.""" - return await db.fetch_all(sql) +async def get_user(user_id: int) -> dict: + """Only agents with Trust Level 2+ can read user data.""" + return await db.fetch_one("SELECT * FROM users WHERE id = $1", user_id) -@server.tool(min_trust_level=0) +@server.tool(min_trust_level=1) async def list_tables() -> list[str]: - """Any authenticated agent can list available tables.""" + """Agents with a valid badge (Trust Level 1+) can list tables.""" return await db.get_table_names() # Run the server (stdio transport) @@ -468,7 +471,7 @@ ruff check capiscio_mcp |---------|-------------|---------| | [Agent Guard](https://github.com/capiscio/capiscio-sdk-python) | Runtime trust verification for A2A agents | `pip install capiscio-sdk` | | [CapiscIO CLI](https://github.com/capiscio/capiscio-python) | Agent validation for CI/CD pipelines | `pip install capiscio` | -| [capiscio-core](https://github.com/capiscio/capiscio-core) | Go library, CLI binary, and gateway | `go install` | +| [capiscio-core](https://github.com/capiscio/capiscio-core) | Go library, CLI binary, and gateway | [Install guide](https://github.com/capiscio/capiscio-core#install) | [Documentation](https://docs.capisc.io) · [Website](https://capisc.io) · [Platform](https://app.capisc.io)