Metadata-Version: 2.4
Name: tsrct-mcp
Version: 0.1.3
Summary: MCP server for the tsrct cryptographic content verification protocol
Project-URL: Homepage, https://tsrct.io
Project-URL: Documentation, https://docs.tsrct.io
Project-URL: Repository, https://github.com/tsrct/tsrct-mcp
License: MIT License
        
        Copyright (c) 2024 tsrct
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: a2a,cryptography,mcp,pki,tdoc,tsrct
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: qrcode>=7.0
Description-Content-Type: text/markdown

# tsrct MCP Server

A Python-native Model Context Protocol (MCP) server for the `tsrct` protocol — cryptographic non-repudiation and real-time authority for agent actions.

## Quick Start

```bash
# Install and run directly (no clone needed)
uvx tsrct-mcp

# Or install permanently
pip install tsrct-mcp
```

### Add to Claude Code

```bash
claude mcp add tsrct-mcp uvx tsrct-mcp
```

### Add to Gemini CLI

```bash
gemini mcp add tsrct-mcp uvx tsrct-mcp
```

### Add to any MCP host (JSON config)

```json
{
  "mcpServers": {
    "tsrct-mcp": {
      "command": "uvx",
      "args": ["tsrct-mcp"]
    }
  }
}
```

## Features

- **Pure Python Implementation**: No external binaries required for cryptography or protocol logic.
- **T-Doc Support**: Full implementation of the `header.body.signature` format with the SHA-256 body-string quirk.
- **Verhoeff Validation**: Native implementation of the 25-digit UID validation.
- **Agent Onboarding**: Tool to generate QR codes for mobile app blessing.
- **A2A Messaging**: Encrypt-then-Sign pipeline for secure agent-to-agent communication.

## Setup

Before using the MCP tools, establish your tsrct identity:

1. Download and install the **tsrct** mobile application on your mobile device
   1. Android App: https://play.google.com/store/apps/details?id=io.tsrct.app
   2. iOS via Testflight: https://testflight.apple.com/join/JGmKXSL6
   3. Mobile app user guide: https://docs.tsrct.io/mobile-app.html
2. Launch the app and create your decentralized cryptographic account.
3. Go to the credentials wallet within the app and add your primary identity card via **self-attestation** (attesting your name and title). This assigns you an active parent DDX authority record.
4. Once the MCP server has been added to your preferred LLM host, prompt the AI agent to run `"propose agent registration"`. This initiates the deferred onboarding handshake, displaying a terminal QR code for you to scan with your mobile app and bless the local agent, permanently binding its cryptographic keys to your verified tsrct identity.

### Identity Storage & Security

All local cryptographic keys (RS256 signing and RSA-OAEP encryption key pairs), user coordinates (`AGENT_SRC`), and authorized session identifiers are securely written and persisted locally inside your user home directory at:

```text
~/.tsrct/identity.json
```

This isolates your private keys away from the Git workspace to prevent accidental credential leakage, while allowing the `tsrct-mcp` server to automatically load and sign transactions dynamically.

## MCP Resources

The following static/dynamic resources are exposed by the server:

* **`tsrct://identity`**: Returns the current agent identity details (assigned UID, key ID, parent user UID, virtual ID, and persistence status).
  * *Usage Prompt:* "Show me my current tsrct agent identity status and details."
* **`tsrct://docs/manual`**: Retrieves the official tsrct system protocol manual (v1.0), specifying T-Doc format details, Verhoeff checksums, and schema constraints.
  * *Usage Prompt:* "Fetch the core tsrct protocol manual so we can review the document class schema."
* **`tsrct://docs/mcp-guide`**: Detailed operations guide on deferred onboarding, blessing handshakes, and cryptographic verification flows.
  * *Usage Prompt:* "Get the tsrct MCP integration and operations guide."

## MCP Tools

### 1. Agent Onboarding & Registration

* **`propose_agent_registration(agent_name: str, agent_description: str)`**
  * *What it does:* Initiates the cryptographic blessing session on the tsrct ledger. It registers your local public keys (JWKS) and renders an ASCII QR code in your terminal.
  * *Usage Prompt:* "Register a new agent named 'my-agent' with the description 'Local development helper'."
* **`wait_for_registration(session_id: str)`**
  * *What it does:* Polls the authentication API until the user scans the QR code with their mobile app and authorizes the session. Saves the finalized identity into `identity.json`.
  * *Usage Prompt:* "Wait and poll for the registration session 'abc123xyz' to complete."

### 2. Document Creation & Publishing

* **`create_and_publish_tdoc(text: str, description: str, content_type: str, ddx_uid: str)`**
  * *What it does:* Creates, signs (RS256), and publishes a public/private `cls:doc` T-Doc onto the tsrct network. Supports optional real-time DDX credential countersigning handshakes.
  * *Usage Prompt:* "Publish a new text T-Doc containing 'Hello tsrct Network' with the description 'Greeting doc'."
* **`publish_image_file(file_path: str, description: str, ddx_uid: str)`**
  * *What it does:* Reads a local `.png` or `.jpg` file, encodes it as a base64url `typ:blob`, signs it, and publishes it onto the ledger.
  * *Usage Prompt:* "Publish the local image at './my-image.png' as a T-Doc."

### 3. Messaging & Secure A2A Communication

* **`send_a2a_message(recipient_uid: str, message: str)`**
  * *What it does:* Sends an end-to-end encrypted message to another agent. Discovers their public encryption key, encrypts the payload, signs the ciphertext, and transmits the resulting private T-Doc.
  * *Usage Prompt:* "Send a secure message 'Top Secret payload' to the recipient '2345678901234567890123456'."
* **`send_target_message(recipient_uid: str, message: str, file_path: str, description: str)`**
  * *What it does:* Sends a secure, private, and non-listable T-Doc document specifically targeted to another recipient. Supports sending either standard text messages or rich files (images, PDFs, binary documents) provided via `file_path`. Sets access control level to private (`acl:acl_pri`) and directory listing to false (`lst:false`). **Note: The target recipient must have the sender added as a contact (via the contacts section in their mobile app), otherwise the ledger API will reject the transmission.**
  * *Usage Prompt:* "Send a targeted private PDF document at './statement.pdf' with description 'Monthly Report' to recipient '2345678901234567890123456'."

### 4. Fetching & Querying

* **`get_user_documents()`**
  * *What it does:* Uses a signed `x-tsrct-auth` JWT to securely fetch all documents (including unlisted/private ones) registered under your user ID.
  * *Usage Prompt:* "Fetch all of my user's registered documents."
* **`get_my_recent_published_messages()`**
  * *What it does:* Fetches the most recently sent T-Doc messages securely from the API using authentication JWT headers.
  * *Usage Prompt:* "Retrieve my recently published messages."
* **`get_user_recd_documents()`**
  * *What it does:* Fetches all T-Doc documents/messages where the authorized user is the recipient (`tgt` field matches the user's UID).
  * *Usage Prompt:* "Load and list all recent documents where I am the recipient."
* **`get_logged_in_user_ddxes(uid: str, optional)`**
  * *What it does:* Fetches all valid active DDX credentials and entitlements currently assigned to the logged-in agent (or a specified UID). Call this before `create_and_publish_tdoc` when you need a `ddx_uid`.
  * *Usage Prompt:* "Check what DDX entitlements are available for my user."

### 5. T-Doc Retrieval & Analysis

* **`get_tdoc_header(uid: str)`**
  * *What it does:* Retrieves only the JSON metadata header of a registered T-Doc by its UID.
  * *Usage Prompt:* "Fetch the T-Doc header for UID '12345.doc.abc123xyz'."
* **`get_full_tdoc(uid: str)`**
  * *What it does:* Retrieves the raw, single-line dot-separated T-Doc representation (`header.body.signature`).
  * *Usage Prompt:* "Get the full raw T-Doc string for '12345.doc.abc123xyz'."
* **`get_tdoc_body(uid: str)`**
  * *What it does:* Fetches the body, decodes the base64, and dynamically parses/renders it based on Content-Type (pretty-printed JSON, Markdown-embedded inline image, text, or hex-binary stream).
  * *Usage Prompt:* "Read and decode the body of the T-Doc '12345.doc.abc123xyz'."

### 6. Verification & Validation

* **`validate_tdoc(tdoc_raw: str, uid: str)`**
  * *What it does:* Performs comprehensive cryptographic validation of a local or fetched T-Doc string. It tests formatting, resolves the signer's JWKS, validates the SHA-256 body-string quirk hash, and verifies the RS256 signature locally.
  * *Usage Prompt:* "Validate the cryptographic signature and integrity of T-Doc '12345.doc.abc123xyz'."
