Metadata-Version: 2.4
Name: synpareia-trust-mcp
Version: 0.6.3
Summary: Trust tools for agent-to-agent dealings — prove, vet, and bind with verifiable evidence (MCP server)
Project-URL: Homepage, https://synpareia.com
Project-URL: Repository, https://github.com/synpareia/trust-mcp
Project-URL: Issues, https://github.com/synpareia/trust-mcp/issues
Project-URL: Changelog, https://github.com/synpareia/trust-mcp/blob/main/CHANGELOG.md
Author-email: Synpareia <hello@synpareia.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,identity,mcp,trust,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: idna>=3.15
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: python-multipart>=0.0.30
Requires-Dist: synpareia[profile,witness]>=0.6.0
Provides-Extra: dev
Requires-Dist: bandit>=1.8; extra == 'dev'
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: starlette>=1.3.1; extra == 'dev'
Description-Content-Type: text/markdown

# Synpareia Trust Toolkit

Verifiable dealings with other agents: **prove** what you did, **vet** who you're dealing with, and **bind** agreements so anyone can check them — no platform trust required.

An MCP server that gives your agent a cryptographic identity and the trust tools for the moments when something is at stake with another agent:

- **About to rely on another agent?** Vet them first — `evaluate_agent` aggregates your own history with them, attested network reputation, and external providers into one read.
- **In an interaction you may need to prove your side of later?** `recording_start` opens a tamper-evident, hash-linked record both parties can contribute to; export a portable proof anyone can verify.
- **Two agents assessing something that must be provably independent?** `prove_independence` seals each assessment before either side reveals — no anchoring, no retconning.

Everything your agent signs, records, or seals **verifies offline, forever** — proofs are pure cryptography and don't depend on synpareia staying up. The synpareia network (on by default) adds what local crypto can't: discovery, and reputation that carries across counterparties.

## Install

### Claude Code / Claude Desktop

Add to your MCP configuration:

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

### Any MCP-compatible agent

```bash
pip install synpareia-trust-mcp
synpareia-trust-mcp
```

## Tools

Start by calling `orient` — it maps your situation to the right tools and points you to the relevant `learn` guide. The full surface:

| Tool | What it does | Offline? |
|------|-------------|:-------:|
| `orient` | Map your situation to the right tools; call after any context loss | Yes |
| `learn` | Get a focused guide for one area (usage, examples, pitfalls) | Yes |
| `make_claim` | Sign content with your private key — proves authorship | Yes |
| `verify_claim` | Verify another agent's signature, commitment, or identity claim | Yes |
| `prove_independence` | Commit to an assessment before seeing the other party's | Yes |
| `encode_signed` | Wrap content in a self-verifying signed envelope for any transport | Yes |
| `decode_signed` | Verify a signed envelope and recover its content + signer | Yes |
| `recording_start` | Begin a verified interaction record | Yes |
| `recording_append` | Record a message or event | Yes |
| `recording_end` | Close and optionally rate | Yes |
| `recording_proof` | Export portable, verifiable proof | Yes |
| `recording_list` | List recordings (active and closed) | Yes |
| `remember_counterparty` | Record a counterparty in your local memory | Yes |
| `recall_counterparty` | Look up what you know about a counterparty | Yes |
| `add_evaluation` | Attach your own note/score to a counterparty | Yes |
| `find_evaluations` | Search your evaluations by tag | Yes |
| `witness_info` | Witness identity, public key, service URL | No |
| `witness_seal_timestamp` | Timestamp seal over a block hash | No |
| `witness_seal_state` | State seal over a chain head | No |
| `witness_verify_seal` | Offline verification of either seal type | Yes |
| `witness_submit_blind` | Submit a blind conclusion through the witness | No |
| `witness_get_blind` | Retrieve a prior blind conclusion | No |
| `evaluate_agent` | Multi-provider trust evaluation (synpareia, Moltbook, MolTrust) | No |
| `attested_reputation` | Witness-attested reputation across providers | No |
| `check_media_signals` | Reputation signals for an external handle/namespace | No |
| `publish_profile` | Publish your agent card to the synpareia directory | No |
| `get_profile` | Fetch a counterparty's published agent card | No |
| `update_profile_policy` | Update fields on your published card | No |
| `enable_persistence` | Opt in to directory persistence for chosen scopes | No |
| `disable_persistence` | Withdraw a persistence opt-in | No |
| `delete_profile_history` | Delete a prior published card version | No |
| `delete_profile` | Tombstone your published card | No |

17 of the 32 tools work fully offline (identity, signing, recording, commitments, local counterparty memory, and offline seal verification). The 15 network-touching tools — the `witness_*` service calls, the reputation lookups (`evaluate_agent`, `attested_reputation`, `check_media_signals`), and the directory tools (`publish_profile`/`get_profile` + persistence/deletion) — need a reachable witness or provider.

### Upgrading from 0.2.0

The tool surface was reshaped in 0.3.0. `sign_content` → `make_claim`, `verify_signature` → `verify_claim`, `start_conversation`/`end_conversation` → `recording_start`/`recording_end`, and so on. See `CHANGELOG.md` for the full migration table — old names were removed outright, no shim.

## How It Works

The Trust Toolkit is built on [synpareia](https://pypi.org/project/synpareia/) — cryptographic primitives for AI agent identity. Your agent gets an Ed25519 keypair and a DID (Decentralized Identifier). Every signed statement is verifiable. Every conversation is hash-linked and tamper-evident.

**Identity is local.** Derived from your cryptographic keys, not from a server. Works offline, portable across platforms.

**Trust builds over time.** Each verified conversation adds to your agent's reputation. The more agents that participate, the more meaningful reputation becomes.

**Privacy by default.** Selective disclosure means your agent controls exactly what's visible, and to whom.

**Want to build with the primitives rather than use the tools?** That's the [synpareia SDK](https://pypi.org/project/synpareia/) — custom chain schemas, embedded verification in your own service, batch operations. Call `learn("under-the-hood")` for the tool→primitive map and graduation criteria.

## Example Scenarios

### Verifying a counterparty

Your agent is about to delegate a task to another agent. First, check trust across every configured provider:

```
-> evaluate_agent(namespace="synpareia", id="did:synpareia:a1b2c3...")

tier1: (none — no prior contact in your local journal)
tier2: (namespace=synpareia has no Tier-2 adapter)
tier3:
  synpareia — reputation 0.92, 47 verified conversations, member since 2026-03
  moltrust  — score 4.6/5 across 18 ratings
tier4_available: true  (synpareia DID — encode_signed / decode_signed work)
```

### Making a provably independent assessment

Two agents need to rate a proposal independently:

```
-> prove_independence("Rating: 4/5 -- strong technical approach, weak go-to-market")

Committed. commitment_hash: 7f3a...  nonce_b64: cH/iD5Pm...
Share ONLY the hash. Keep the nonce secret until reveal.

[... other agent reveals their rating ...]

-> verify_claim(claim_type="commitment", commitment_hash="7f3a...",
                content="Rating: 4/5 -- strong technical approach, weak go-to-market",
                nonce_b64="cH/iD5Pm...")

Verified: content matches the sealed commitment.
The assessment was committed before being revealed.
```

### Recording an important interaction

```
-> recording_start("Task delegation negotiation with Agent Y")

Recording. Recording ID: rec_x7y8z9

[... interaction happens, recording_append for each exchange ...]

-> recording_end("rec_x7y8z9", rating=4, notes="Delivered on time, good quality")

Recording closed. 12 blocks, signed and hash-linked.

-> recording_proof("rec_x7y8z9")

Exported: 4.2KB JSON, independently verifiable with synpareia.verify_export()
```

## Configuration

Environment variables (all optional):

| Variable | Default | Description |
|----------|---------|------------|
| `SYNPAREIA_DATA_DIR` | `~/.synpareia` | Where to store profile and conversations |
| `SYNPAREIA_DISPLAY_NAME` | *(none)* | Human-readable name for your agent |
| `SYNPAREIA_NETWORK_URL` | `https://synpareia.fly.dev` | Synpareia network API endpoint. Set to `none` (or `off`/`disabled`, or explicitly set-but-empty) for fully-local operation; set a URL for self-hosted instances |
| `SYNPAREIA_WITNESS_URL` | `https://synpareia-witness.fly.dev` | Witness service endpoint for `witness_*` tools. Same `none` opt-out |
| `SYNPAREIA_AUTO_REGISTER` | `false` | Register profile on network automatically (never implicit — publishing is always an explicit tool call unless you enable this) |

## Data, storage, and privacy

The Trust Toolkit is **local-first**. Every file the toolkit creates lives under
`SYNPAREIA_DATA_DIR` (default `~/.synpareia`) on the machine running your agent.
Nothing is *stored* off-machine, and nothing is sent anywhere except when a
network-touching tool is invoked. Since 0.6 the witness and network endpoints
point at the live synpareia services by default, so those tools work out of the
box — set `SYNPAREIA_NETWORK_URL=none` / `SYNPAREIA_WITNESS_URL=none` for
fully-offline operation. Publishing a profile is always an explicit act
(`publish_profile`); nothing auto-registers.

What's stored:

- **Profile** (`profile.json`, mode `0600`) — your agent's Ed25519 keypair and
  display name. The private key never leaves the file.
- **Conversation chains** (`conversations/<chain_id>/`) — your agent's signed
  records of conversations and claims, linked into a chain so any tampering is
  detectable.
- **Counterparty journal** (`counterparties.json`, mode `0600`) — your agent's
  notes about other agents you've encountered: their IDs, your evaluations,
  signed claims they've made to you. **This is your local log; entries are
  visible only to you and your agent.** Other agents do not see your journal.
  When you record an evaluation about a counterparty, that observation stays on
  your disk — there is no automatic upload, no shared reputation database, no
  cross-agent broadcast.
- **Recordings** (`recordings/<id>/`) — full message-by-message logs of
  conversations you explicitly asked the toolkit to record. Same locality
  guarantees.

What flows off-machine (only when the corresponding tool is invoked):

- **Tier-2 platform queries** — if `SYNPAREIA_MOLTBOOK_API_URL` or other
  Tier-2 adapter URLs are set, `check_media_signals` calls those endpoints with
  the counterparty's handle. Otherwise, no network calls.
- **Tier-3 attestation queries** — `attested_reputation` queries the
  configured services (the live synpareia network by default;
  `SYNPAREIA_MOLTRUST_API_KEY` only if set). Opt out with
  `SYNPAREIA_NETWORK_URL=none` for no network calls.
- **Witness service** — the `witness_*` tools talk to the configured witness
  (the live synpareia witness by default; opt out with
  `SYNPAREIA_WITNESS_URL=none`) to obtain timestamp seals. The witness only sees
  hashes and signatures, never your content. For **timestamp and state seals**
  the current synpareia witness is sparse-witness (Position 4): it does not
  persist `requester_id`, so the seal is not linkable to your identity beyond
  what you re-link yourself. **Exception — blind conclusions:**
  `witness_submit_blind` submits a self-asserted party DID, which the witness
  *does* retain (as `party_a_id`/`party_b_id`, and on the underlying seals) so
  the two parties can later be matched at reveal. If unlinkability matters for a
  blind conclusion, submit under a throwaway identity.

Subject-rights / GDPR notes (where the GDPR applies to your agent's
operations):

- All journal data lives on the data subject's own machine. Erasure is
  achieved by deleting the relevant record — there is no `forget_counterparty`
  tool yet; today, edit `counterparties.json` directly.
- The toolkit imposes no retention period — observations persist until you
  delete them. If your operating environment requires a maximum retention,
  enforce it externally.
- The toolkit creates no shadow profiles: counterparties are recorded only
  when your agent explicitly calls `remember_counterparty`. There is no
  ambient observation.

This is not legal advice; review with counsel for your specific deployment.

## Built on

- [synpareia](https://pypi.org/project/synpareia/) — cryptographic primitives (Ed25519, SHA-256, hash-linked chains)
- [MCP](https://modelcontextprotocol.io/) — Model Context Protocol for AI tool integration

## License

Apache 2.0

<!-- mcp-name: io.github.synpareia/trust-mcp -->
