# Matías Context MCP

A thin, local, read-only MCP gateway over an existing ecosystem of governed context documents and producer manifests.

The gateway exposes logical resources through MCP without granting arbitrary filesystem access or duplicating the source systems' contracts.

## Why this exists

The underlying systems already produce and govern:

- context-source metadata;
- integration contracts;
- run records;
- manifests;
- evidence-selection artifacts;
- provenance and checksums.

Before this gateway, every AI client needed repository-specific path knowledge and custom adapters.

This project adds a narrow MCP interface:

```text
MCP client
→ logical resource URI
→ registry lookup
→ authorization
→ canonical path containment
→ bounded read
→ normalization
→ provenance-rich response
```

The source repositories remain authoritative.

## Current status

**resource-only v0.1 MVP: CLOSED**

Working:

* Python MCP server over local `stdio`;
* MCP initialization and capability negotiation;
* resources capability only;
* generated four-source catalog;
* source descriptors;
* governed context-document reads;
* explicit logical-document mappings;
* canonical root-containment checks;
* symlink-escape rejection;
* bounded UTF-8 Markdown and JSON reads;
* SHA-256, size, authority and modification metadata;
* deterministic domain errors;
* real read from KB Contracts;
* everyday and acceptance-probe MCP clients over real `stdio` sessions;
* no tools, prompts, writes or arbitrary filesystem access.

## Resource namespace

```text
matias-context://catalog/sources
matias-context://source/{source_id}
matias-context://source/{source_id}/document/{document_id}
matias-context://manifest/{producer_id}/{manifest_id}
```

The client never supplies or receives a physical filesystem path.

## Integrated systems

| Source            | Gateway role                         |
| ----------------- | ------------------------------------ |
| Context Routing   | Published routing projection         |
| KB Contracts      | Authoritative integration contracts  |
| Knowledge Inspect | Run and manifest producer            |
| KB Artifacts      | Governed evidence-selection producer |

## Trust boundary

The gateway is structurally read-only.

It does not provide:

* raw path parameters;
* recursive directory browsing;
* arbitrary filesystem reads;
* shell or subprocess execution;
* SQL;
* vector-store access;
* repository mutations;
* manifest repair;
* pipeline execution;
* prompts, tools, sampling or elicitation;
* HTTP transport or cloud deployment.

Every filesystem-backed read passes through:

1. strict URI parsing;
2. registry lookup;
3. explicit logical mapping;
4. canonical path resolution;
5. root-containment validation;
6. regular-file and format checks;
7. size enforcement;
8. bounded binary reading;
9. strict UTF-8 and format normalization.

## Requirements

* Python 3.10+
* MCP Python SDK 1.28.1
* local checkouts of the configured sources

## Installation

```bash
python3 -m pip install -e '.[dev]'
```

## Configuration

The server reads a server-owned JSON mount configuration:

```bash
export MATIAS_CONTEXT_GATEWAY_CONFIG="$PWD/config/sources.example.json"

export CONTEXT_ROUTING_ROOT="$HOME/repos/context-routing"
export KB_CONTRACTS_ROOT="$HOME/repos/kb-contracts"
export KNOWLEDGE_INSPECT_ROOT="$HOME/repos/knowledge-inspect"
export KB_ARTIFACTS_ROOT="$HOME/repos/kb-artifacts"
```

These roots are operator configuration. They are not MCP client roots and cannot be changed by a client.

## Run the server

```bash
python3 -m matias_context_mcp
```

The server uses MCP over `stdio`. Protocol traffic is the only permitted output on `stdout`; operational diagnostics go to `stderr`.

## Read resources from the shell

`mctx` is the everyday client. Each command starts the configured server, initializes a real MCP session, performs one resource operation, and prints formatted JSON to `stdout`:

```bash
mctx list
mctx templates

# Catalog and source descriptor
mctx read 'matias-context://catalog/sources'
mctx read 'matias-context://source/kb-contracts'

# Governed context document
mctx read \
  'matias-context://source/knowledge-inspect/document/artifact-surface'

# Producer manifests (replace IDs with configured, existing run IDs)
mctx read \
  'matias-context://manifest/knowledge-inspect/2026-07-27T180000Z'
mctx read \
  'matias-context://manifest/kb-artifacts/selection-2026-07-27T180000Z'

# Extract the normalized document body
mctx read \
  'matias-context://source/knowledge-inspect/document/artifact-surface' \
  | jq -r '.data.text'

# Ordinary shell redirection remains available to the operator
mctx read 'matias-context://catalog/sources' > catalog.json
```

Successful resource envelopes go to `stdout`; diagnostics, server logs, and structured failures go to `stderr`. The client itself does not create output files—the final example uses shell redirection explicitly.

## Diagnostic and acceptance clients

The three command surfaces have deliberately different purposes:

```text
scripts/read_resource.py
    direct kernel diagnostic

mctx
    everyday real-MCP client

scripts/probe_mcp.py
    full acceptance and evidence probe
```

For a direct kernel diagnostic:

```bash
python3 scripts/read_resource.py \
  'matias-context://catalog/sources'

python3 scripts/read_resource.py \
  'matias-context://source/kb-contracts/document/manual-overview'
```

For the acceptance and evidence probe:

```bash
python3 scripts/probe_mcp.py \
  --output-dir artifacts/mvp-evidence
```

The probe records machine-readable initialization, capabilities, listed resources, templates, successful reads and rejection evidence.

## Tests

```bash
python3 -m pytest -q
```

## Architecture

```text
Thin MCP facade
    |
    v
Resource kernel
    ├── frozen exposure profile
    ├── source registry
    ├── URI resolver
    ├── policy gate
    ├── bounded filesystem adapter
    └── normalizer
         |
         v
Explicitly mounted source roots
```

The kernel does not import MCP SDK types and can be reused by a CLI or another transport.

## Design choices

* resources before tools;
* local `stdio` before remote transport;
* explicit mappings before dynamic discovery;
* producer-owned manifests before a universal gateway schema;
* bounded reads before broad format support;
* fail closed rather than guess;
* thin adapter rather than a new knowledge platform.

## Related systems

* Context Routing: [https://github.com/matuteiglesias/context-routing](https://github.com/matuteiglesias/context-routing)
* KB Contracts: [https://github.com/matuteiglesias/kb-contracts](https://github.com/matuteiglesias/kb-contracts)
* Knowledge Inspect: [https://github.com/matuteiglesias/knowledge-inspect](https://github.com/matuteiglesias/knowledge-inspect)
* KB Artifacts: [https://github.com/matuteiglesias/kb-artifacts](https://github.com/matuteiglesias/kb-artifacts)

## Portfolio summary

> Designed and implemented a read-only MCP gateway over an existing ecosystem of governed context sources and producer manifests. The gateway uses logical resource URIs, explicit allowlists, canonical path containment, bounded reads, provenance-rich responses and a transport-independent kernel. It is validated end to end with a real MCP client over local stdio, including capability negotiation and unauthorized-access rejection.