DarkMatter
Tamper-evident records of AI agent decisions. Verify offline, or publish a proof link.
Open source Open in the app JSON README (API)
About
Tamper-evident records of AI agent decisions. Verify offline, or publish a proof link.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- darkmatter-hub
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.1
- Last push
- 2026-08-28T19:50:11Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.darkmatter-hub/mcp-server
README
# DarkMatter MCP Server
Universal MCP server that emits [Context Passport](https://contextpassport.com) records for AI agent decisions and actions. Drop into any MCP-compatible client (Claude Code, Cursor, Cline, Continue, ChatGPT Desktop, Zed, Goose, and others) to give your agent a `commit / verify / replay / export` toolset for verifiable, tamper-evident records.
**Built by [DarkMatter](https://darkmatterhub.ai). Implements [Context Passport v2.0](https://github.com/contextpassport/spec), an open CC0 standard. Records emitted by this server use RFC 8785 (JCS) canonicalization and are byte-equivalent across the Python and TypeScript reference SDKs.**
## Install
In your MCP client's config (`claude_desktop_config.json`, Cursor's `mcp.json`, etc.):
```json
{
"mcpServers": {
"darkmatter": {
"command": "npx",
"args": ["-y", "@darkmatterhub/mcp-server"]
}
}
}
```
Restart the client. Five tools become available to your agent:
- `darkmatter_commit` — record an agent decision or action
- `darkmatter_verify` — check that the chain has not been tampered with
- `darkmatter_replay` — walk the full chain in order
- `darkmatter_export` — produce a portable proof bundle
- `darkmatter_list_sessions` — see what sessions exist locally
## Bundles explain themselves
`darkmatter_export` produces a bundle that a stranger can act on. Alongside the
records it carries the format name, a link to the specification, whether the
chain was intact at export time, and the exact command to verify it in Python or
TypeScript, plus what a failure looks like.
That matters because the bundle is the artifact that leaves your machine. It
goes to an auditor, a regulator or a counterparty who has never heard of this
format, and the whole claim is that they can check it without trusting whoever
sent it. A bundle that does not say how is asking to be trusted.
## Local by default, published when you ask
With no configuration the server keeps every record on your own disk. The
chain verifies offline through `darkmatter_verify`, so you can evaluate the
whole idea without an account.
Set an API key to publish records and get a link somebody else can check:
| Variable | Effect |
|---|---|
| `DARKMATTER_API_KEY` | Publishes each record to DarkMatter and returns a `verify_url`. Get one at [darkmatterhub.ai](https://darkmatterhub.ai). |
| `DARKMATTER_SHARE` | Set to `true` to make published records readable by anyone with the link. Off by default, because publishing is not something to do to your records without being asked. |
| `DARKMATTER_API_URL` | Override the API host. Defaults to `https://darkmatterhub.ai`. |
| `DARKMATTER_MCP_STORE_DIR` | Where local records are written. |
`commit` reports which of the two happened, in the `storage` field. If
publishing fails the record is still committed locally and the error is
returned alongside it, so a network problem cannot cost you the record.
> **Changed in 0.3.0.** Earlier versions returned a
> `https://darkmatterhub.ai/r/{id}` link for every commit while making no
> network calls at all, so the link always 404ed. A verification URL is now
> returned only when there is a published record behind it.
## What gets captured
Whatever the agent (or user) explicitly invokes via `darkmatter_commit`. Auto-capture of every tool call without explicit invocation is a separate component (see [Auto-capture](#auto-capture) below).
Example agent flow:
```
User: Approve the refund for order #1247 and record the decision.
Agent: Calls refund_order(1247).
Agent: Calls darkmatter_commit({
input: "Approve refund for order #1247",
output: "Approved. $84.00 refunded to original payment method.",
role: "compliance",
event_type: "commit"
})
Result: { ok: true, passport: {...}, storage: "local", verify_url: null,
note: "Saved locally and verifiable offline..." }
```
The passport is signed (if a key is configured), hash-chained to the previous commit in the session, and stored locally at `~/.darkmatter/mcp/<session_id>/chain.jsonl`.
## Storage
Default: local-only. Passports never leave the machine.
```
~/.darkmatter/mcp/
├── default/
│ ├── chain.jsonl # append-only stream of all commits
│ └── latest.json # most recent passport (used as parent for the next)
└── <other-session-id>/
└── ...
```
To forward each passport to a DarkMatter receiving server in addition to local storage, set:
```bash
export DARKMATTER_API_KEY="dm_sk_..."
```
The forwarding is best-effort and never blocks the agent's tool call. Local storage remains the source of truth.
## Auto-capture
The MCP server captures only what the agent explicitly invokes. To auto-capture every tool call and turn boundary in a specific dev tool (without the agent having to remember to call `darkmatter_commit`), install one of the dev-tool-specific adapters:
- [darkmatter-hub/claude-code](https://github.com/darkmatter-hub/claude-code) — auto-capture for Claude Code (Anthropic)
- Cursor adapter — planned
- OpenAI Codex adapter — planned
- Aider adapter — community-built welcome
Each adapter hooks into its specific dev tool's event lifecycle and routes events through this MCP server's `darkmatter_commit` tool. One canonical endpoint, many capture surfaces.
## Verification
Records are valid Context Passport v2.0 artifacts. Verify with any conformant implementation:
```bash
pip install context-passport context-passport-conformance
context-passport-conformance --level signed # 9/9 vectors, no --vectors-dir needed
```
The conformance package ships its vectors inside the wheel, so this is a one-line check against the public reference suite.
Or use the offline reference verifier directly on the JSONL file:
```python
import json
from context_passport import verify_chain
with open("~/.darkmatter/mcp/default/chain.jsonl") as f:
chain = [json.loads(line) for line in f]
print(verify_chain(chain)) # True if intact, False if tampered
```
## Why MCP
MCP (Model Context Protocol) is becoming the universal interop layer for AI tools. Writing this server once means it works in every MCP-compatible client without per-client integration code. See the [Context Passport for MCP proposal](https://github.com/contextpassport/spec/blob/main/proposals/context-passport-for-mcp.md) for the broader architectural rationale.
## License
Apache-2.0. See `LICENSE`.
The Context Passport schema this server implements is released separately under CC0 1.0 at [github.com/contextpassport/spec](https://github.com/contextpassport/spec).
## Related repositories
- [github.com/contextpassport/spec](https://github.com/contextpassport/spec) — the open standard
- [github.com/contextpassport/python](https://github.com/contextpassport/python) — Python reference SDK
- [github.com/contextpassport/typescript](https://github.com/contextpassport/typescript) — TypeScript reference SDK
- [github.com/darkmatter-hub/claude-code](https://github.com/darkmatter-hub/claude-code) — auto-capture for Claude Code
- [github.com/darkmatter-hub/darkmatter](https://github.com/darkmatter-hub/darkmatter) — DarkMatter receiving server