Metadata-Version: 2.4
Name: phionyx-mcp-server
Version: 0.2.0
Summary: Phionyx MCP trust boundary governance layer — descriptor signing, runtime guardrail, tamper-evident audit chain for MCP-capable hosts.
Author-email: Ali Toygar Abak <founder@phionyx.ai>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://phionyx.ai
Project-URL: Repository, https://github.com/halvrenofviryel/phionyx-research
Project-URL: Documentation, https://github.com/halvrenofviryel/phionyx-research/tree/main/examples/envelopes/rge_v0_2
Project-URL: Bug Tracker, https://github.com/halvrenofviryel/phionyx-research/issues
Keywords: mcp,model-context-protocol,ai-governance,tool-poisoning-defense,audit-chain,phionyx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.27.0
Requires-Dist: phionyx-core>=0.3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=42.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# phionyx-mcp-server

> The MCP trust boundary in the Phionyx runtime — descriptor signing, signed
> evidence envelopes, and a tamper-evident audit chain over third-party MCP tool calls.

`phionyx-mcp-server` sits between an MCP-capable host (Claude Desktop, Cursor, Zed,
VS Code, JetBrains) and any third-party MCP server it talks to, producing
tamper-evident evidence at every trust-boundary crossing. It closes a security gap
the MCP specification
([2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25)) explicitly
defers to implementors:

> *"MCP itself cannot enforce these security principles at the protocol level;
> implementors SHOULD..."*

The threat surface is aligned with
arXiv:[2512.06556](https://arxiv.org/abs/2512.06556) (Jamshidi et al., *Securing the
Model Context Protocol*) — tool poisoning, shadowing, rug pulls.

## Where it fits

Phionyx ships three distinct things, each on its own version line — don't
cross-attribute them:

- **Engine — `phionyx-core`:** the deterministic-cognition runtime (46-block
  canonical pipeline, kill switch, HITL queue, ethics/safety gates, signed audit
  chain). `pip install phionyx-core`.
- **Gate — `phionyx-pipeline-mcp`:** an agent self-claim gate that verifies
  "I fixed / I tested / this changed" against the repository's actual diff.
- **Standard — `phionyx-evaluation-standard`:** a vendor-neutral spec defining
  L0-L3 (evaluation maturity), D0-D3 (determinism), and CG-L0…CG-L5
  (claim-governance).

**This package** is the outward MCP **trust boundary** — it produces signed,
hash-chained evidence over third-party MCP tool calls. It interoperates with the gate
through a shared session trace, so both governance surfaces share one view.

## Status

**v0.2.0.** Five of eight capabilities are fully implemented; three are explicit
stubs that return structured `not_implemented` markers (callers can detect server
maturity). The two load-bearing capabilities — descriptor verification and
tool-call audit — are live. Envelopes follow **RGE v0.2** (Runtime Governance
Envelope).

| # | Capability | Status |
|---|---|---|
| 1 | Tool descriptor hash | ✅ implemented |
| 2 | Descriptor change detection | ✅ implemented |
| 3 | Tool permission scope | 🟡 envelope field populated; policy logic stub |
| 4 | Tool call I/O hash | ✅ implemented |
| 5 | User approval state | 🟡 envelope field populated; UX surface stub |
| 6 | Runtime anomaly record | 🟡 records to the audit side-log; drift scoring stub |
| 7 | Signed evidence envelope | ✅ implemented (RGE v0.2) |
| 8 | Chain verification command | ✅ implemented (`phionyx-mcp verify-chain`) |

## Install

```bash
pip install phionyx-mcp-server
phionyx-mcp --help
```

## Use — as an MCP server

Add to your MCP-capable host (Claude Desktop example):

```json
{
  "mcpServers": {
    "phionyx-governance": { "command": "phionyx-mcp-server" }
  }
}
```

The host then sees four production MCP tools:

- `verify_tool_descriptor(descriptor, baseline_hash)` — hash and compare against an
  approved baseline (full descriptor, including `protocolVersion`).
- `record_tool_call(turn_index, user_text, producer, …, trace_id=None)` — emit a
  signed RGE v0.2 envelope. `trace_id` is optional; resolved from `PHIONYX_TRACE_ID`
  or `~/.phionyx/active_trace`.
- `verify_chain_integrity(trace_id=None)` — walk the chain, refuse mixed schemas.
- `query_audit_history(trace_id=None, limit=50)` — replay envelopes for review.

Plus three stub tools returning structured `not_implemented` markers.

## Shared trace with the gate

When installed alongside `phionyx-pipeline-mcp`, the two servers share a single
`trace_id` per session, so one session's evidence spans both governance surfaces:

- `PHIONYX_TRACE_ID` env var → highest precedence.
- `PHIONYX_ACTIVE_TRACE_FILE` (default `~/.phionyx/active_trace`) → file fallback.
- The first caller generates a UUID-derived trace and persists it.

## Use — as a CLI

```bash
phionyx-mcp head --trace trace-abc123          # current chain head
phionyx-mcp verify-chain --trace trace-abc123  # walk + verify the chain
phionyx-mcp show --trace trace-abc123 --turn 7 # show one envelope
```

The CLI exits 0 on a valid chain, 1 on tamper/break, 2 on invocation error.

## Persistence

Envelopes are written under `$PHIONYX_MCP_AUDIT_ROOT` (default `~/.phionyx/mcp_audit/`):

```
<root>/<trace_id>/chain.jsonl      (append-only index)
<root>/<trace_id>/<turn:06d>.json  (full canonical-JSON envelope)
```

Swap the persistence layer by passing an alternative `EnvelopeStore`-protocol
implementation (S3, DynamoDB, …).

## Schema — RGE v0.2

Envelopes conform to **RGE v0.2** (Runtime Governance Envelope). The signature
covers all envelope content except the self-referential
`mcp_tool_audit.signed_envelope_ref`. The schema, RFC, and worked examples ship in
this repository.

## Tests

```bash
pip install -e .
pytest -q
```

The suite pins descriptor-hash semantics (full descriptor including
`protocolVersion`), RGE v0.2 schema conformance (jsonschema Draft 2020-12), and
hash-chain integrity (tamper, reorder, and mixed-schema detection).

## See also

- **Engine** — [phionyx-core on PyPI](https://pypi.org/project/phionyx-core/)
- **Gate** — [phionyx-pipeline-mcp](https://github.com/halvrenofviryel/phionyx-pipeline-mcp)
- **Standard** — [phionyx-evaluation-standard](https://github.com/halvrenofviryel/phionyx-evaluation-standard)
- **Runtime narrative** — [phionyx.ai](https://phionyx.ai)

## License

AGPL-3.0-or-later.
