Universal Agent Middleware (UAM) v0.5.1rc1

Public Preview RC1 — read-only MCP observation for local codebases

UAM is a vendor-neutral, local-first middleware that lets any reasoning client (ChatGPT, Claude, Cursor, future agents) observe your local project workspaces in real time through a secure read-only interface — with project-level reality coverage, lifecycle tracking, and observation-based diagnostics.

What it does

Reasoning client (new session, no history needed)
       │
       ▼
  UAM MCP App (19 read-only tools)
       │
       ▼
  Optional secure MCP tunnel (outbound-only)
       │
       ▼
  Your local machine
       │
       ▼
  Registered workspaces + project reality
  (my-app, api-service, etc.)

A new conversation can read live repository state — HEAD, branch, files, diffs, search, project reality coverage — without copy-paste and without granting write access.

Quick start

# Install
python -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp]"

# Register workspaces
cp config/workspaces.example.json config/workspaces.json
# Edit workspace roots to match your machine

# Optional: root scope registry for autonomous discovery
cp examples/root_scopes.example.json config/root_scopes.json

# Local MCP smoke test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
  uam mcp-sdk-stdio --profile session-read \
    --registry config/workspaces.json \
    --state-dir ~/.local/share/uam

For remote clients, configure an outbound MCP tunnel using your platform credentials. See docs/adapters/MCP.md.

Available MCP tools

All session-read tools expose readOnlyHint=true, destructiveHint=false. No write, exec, merge, deploy, or credential tools are part of the Public Preview contract.

Security model

• Read-only remote surface — no mutation tools exposed in session-read profile
• Path containment — .env, .git/**, ../ traversal all denied
• Prompt injection defense — security is middleware-enforced, not model-dependent
• No credentials in repo — tunnel credentials via environment only
• Outbound-only tunnel — no public inbound listener required (optional adapter)
• Secret firewall — credential-like files denied even under broad scope authority

Architecture

Reasoning clients / humans
ChatGPT · Claude · Gemini · Cursor · Copilot · future agents
                    │
          northbound adapters
   HTTP/OpenAPI · MCP (official SDK) · Agent Plugins
                    │
                    ▼
┌────────────────────────────────────────────────┐
│ Universal Agent Middleware Core                 │
│ workspace registry → policy → observation      │
│ project registry → coverage diagnostics        │
│ audit → execution contract → result review     │
└──────────────────┬─────────────────────────────┘
                   │                     │
             READ ONLY                 .state/
                   │              contracts/results/audit
                   ▼
       registered project workspaces
       my-app · api-service · others

Core invariants

• Vendor-neutral core: no OpenAI/Anthropic/Cursor/GitHub dependency
• Project sovereignty: target project SSOT remains authoritative
• Read-only boundary: session-read profile grants no write, shell, commit, push, merge, or deploy
• Observation ≠ Authority: UAM reports reality; project governance decides actions
• Separate state: UAM state is physically disjoint from target workspaces
• Evidence-bound execution: (v0.2+ contracts; legacy LocalExecutor is experimental)

Project reality model (v0.3.1+)

UAM tracks multi-instance projects with orthogonal dimensions:

• role — structural function: canonical-main, candidate, review-carrier
• lifecycle — temporal state: active, landed, stale, superseded
• coverage — observation completeness per truth surface

Coverage states: observed, externally_verified, not_applicable, not_observed, not_registered

Project-specific observation profiles in config/project-observation-profiles/ (local-only, gitignored) define per-project requirements without embedding project semantics into UAM core.

Documentation

• docs/REALITY_PREAMBLE.md — Reality Preamble protocol
• docs/BACKLOG.md — Roadmap and hardening priorities
• docs/adapters/MCP.md — MCP adapter setup
• docs/oss/public-profile-contract.md — Public Preview supported surface
• CHANGELOG.md — Version history
• SECURITY.md — Vulnerability reporting
• CONTRIBUTING.md — Contribution guidelines

Status

v0.5.1rc1 — Public Preview RC1

Public Preview supports SDK stdio session-read profile only. Legacy HTTP adapter and LocalExecutor are experimental and not part of the Preview contract. See docs/oss/public-profile-contract.md.

Deferred: forge/runtime observation, write-capable remote tools, autonomous execution, production OAuth.