rosetta-mcp-workspace 0.4.0

Observable agent workspace control plane for MCP servers, FastMCP gateways, packs, profiles, skills, prompts, resources, and client syncs.

Rosetta MCP Observable Platform

Rosetta MCP is a scaffold for an observable agent workspace control plane. It manages MCP servers, FastMCP gateway profiles, client syncs, packs, skills, prompts, resources, instruction files, env requirements, and infra.

What is included

• Rich/Typer CLI
• FastAPI control plane
• FastMCP gateway skeleton
• Generic graph runtime wrappers for LangGraph/LangChain runnables
• Live LangChain create_agent(...) demos with Rosetta-injected MCP tools, prompts, resources, blobs, transforms, and local/LangSmith trace metadata
• MCP discovery and inspection helpers
• Codex, Deep Agents, and LangChain render targets
• AGENTS.md, CLAUDE.md, SKILL.md, prompt rendering
• Postgres + Alembic scaffold
• Infra folder with Postgres, OTel Collector, Prometheus, Grafana, and Jaeger
• Unit, integration, API, and e2e test scaffolding
• Universal core components for IDs, results, context, security, and pagination
• Observability layer with structlog, Rich, OpenTelemetry, and Prometheus helpers

Install

From PyPI, the planned distribution name is rosetta-mcp-workspace:

python -m pip install "rosetta-mcp-workspace[all]"

The import package remains rosetta_mcp and the console command remains rosetta.

For local development:

pdm install -G :all -d -G :all

That installs all project extras plus all dependency groups. For a smaller day-to-day install, select only the groups you need, for example:

pdm install -G dev -G api -G mcp -G langchain

Copy .env.example to .env for live LLM/MCP traces. Keep real values local; .env is ignored by git.

Validate

Fast syntax and scaffold checks:

make verify-fast

Full validation after installing all groups:

make verify

CLI examples

pdm run rosetta init --scope project
pdm run rosetta add context7 -- npx -y @upstash/context7-mcp
pdm run rosetta list
pdm run rosetta obs config
pdm run rosetta platform doctor
pdm run rosetta verify quick
pdm run rosetta verify plan --no-pytest
pdm run rosetta prompt list
pdm run rosetta skill render mcp-inspection
pdm run rosetta instructions render --target agents
pdm run rosetta fastmcp sync --targets mcp-json,codex,langchain --mode gateway --write

Documentation

The docs build with Sphinx, MyST Markdown, autodoc, Napoleon, and type-hint rendering:

pdm install -G docs
pdm run sphinx-build -W -b html docs docs/_build/html

For local live preview:

pdm run sphinx-autobuild docs docs/_build/html

Read the Docs configuration lives in .readthedocs.yaml.

Graph runtime and live LLM traces

Rosetta includes a generic graph runtime kit under rosetta_mcp.graph_runtime. It is not a broad agent layer. It is the connective tissue between Rosetta registry/profile selections and graph-like runtimes:

• wrap an existing compiled graph or runnable with RosettaGraphHandle
• compile one minimal LangChain v1 create_agent(...) graph with selected MCP tools and injected context
• pass stable runnable config with thread_id, tags, metadata, and trace flags
• inject selected prompts/resources/blobs as system text, messages, state, or availability metadata
• preview FastMCP transform selections such as namespace, visibility, resources-as-tools, and prompts-as-tools

Preview the graph runtime configuration without calling an LLM:

pdm run rosetta graph config \
  --name rosetta-agent \
  --server-mode gateway_only \
  --prompt runtime-contract \
  --prompt-mode system \
  --resource resource://rosetta/demo/integration-goal \
  --resource-mode system \
  --resources-as-tools \
  --prompts-as-tools \
  --trace

Call the real Rosetta gateway status MCP tool and print a local trace:

pdm run rosetta graph status --local-trace

Compile a live LangChain agent, let the LLM call the gateway status tool, and print the message/tool trace:

pdm run rosetta graph agent-smoke --local-trace

Run the richer proof that combines a real MCP tool, local tools, prompt injection, resource/blob injection, transform metadata, and trace output:

pdm run rosetta graph rich-demo --local-trace

Use --langsmith instead of --local-trace only when LANGSMITH_API_KEY is set and you want hosted LangSmith traces. Use repeated --env-file PATH to load additional env files before .env, .env.llm, and .env.mcp.

More detail: Graph Runtime.

Release Status

This repository is configured for standard Python builds and PyPI trusted publishing. The original rosetta-mcp package name is already occupied on PyPI by a different project, so this repository uses rosetta-mcp-workspace as its publishable distribution name.

Release docs: Release And Publishing.

API and gateway listeners

The default root workflow avoids trapping you in foreground listeners.

• make up, make obs, make down, make status, and make logs operate on detached infra services.
• Foreground app listeners are explicit: make serve-api and make serve-gateway.
• Optional local background app listeners are explicit: make api-bg and make gateway-bg.

Run the API in the foreground:

make serve-api
# or
pdm run rosetta api serve

Run the gateway in the foreground:

make serve-gateway

Run local app listeners in the background with pid/log files:

make api-bg
make gateway-bg
make app-status
make app-logs
make app-stop

Smoke test API endpoints:

curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/observability/config
curl http://127.0.0.1:8765/platform/info
curl http://127.0.0.1:8765/verification/plan

Makefile quickstart

The root Makefile is ergonomic. Infra implementation still lives in infra/Makefile, but common commands work from the repo root:

make setup          # install deps, create infra env, run fast checks
make up             # start Postgres in the background
make obs            # start Postgres + OTel + Prometheus + Grafana + Jaeger in the background
make status         # show compose service status
make logs           # tail infra logs
make migrate        # run Alembic migrations
make psql           # open psql
make serve-api      # run FastAPI in the foreground
make serve-gateway  # run FastMCP gateway in the foreground
make api-bg         # optional: run FastAPI in background, log to .rosetta/run/api.log
make gateway-bg     # optional: run gateway in background, log to .rosetta/run/gateway.log
make app-stop       # stop background local app listeners
make down           # stop infra

Namespaced aliases still work:

make infra-up
make infra-migrate
make infra-psql
make db-up
make db-migrate
make obs-up

Open after make obs:

• Grafana: http://localhost:3000
• Prometheus: http://localhost:9090
• Jaeger: http://localhost:16686

Design

Rosetta treats tools, prompts, resources, skills, templates, env requirements, runtimes, and policies as first-class workspace objects. The gateway is the normal interface for clients, while direct config rendering remains a debugging fallback.

The graph runtime layer keeps that same shape for agents: selectors and injection settings are explicit, external graphs are wrapped rather than mutated, and Rosetta-created LangChain agents receive tools/context before compile.

Current root workflow fixes

Use the root Makefile for normal work:

make setup
make up
make migrate
make status
make serve-api

Notes:

• make compile uses pdm run python, so it works even when the shell has no global python executable.
• make migrate delegates to infra/Makefile, waits for Postgres, and passes ROSETTA_MCP_SYNC_DATABASE_URL based on infra/.env.
• Docker Postgres defaults to host port 55432; Alembic no longer tries localhost:5432 unless you override POSTGRES_PORT.
• Foreground listeners are explicit: use make serve-api or make serve-gateway. make api and make gateway remain compatibility aliases.
• If an old Docker volume has a different Postgres password, run make reset.

Built-in catalog workflow

Rosetta includes a starter catalog of common MCP servers, packs, and profiles. Use these to bootstrap a workspace without hand-writing every config.

pdm run rosetta catalog servers
pdm run rosetta pack list
pdm run rosetta profile list

# Install recommended workspace servers into the project registry.
pdm run rosetta profile install workspace

# Or install a focused pack.
pdm run rosetta pack install mcp-dev-pack

# Render gateway configs after installing servers.
pdm run rosetta fastmcp sync --targets mcp-json,codex,langchain --mode gateway --write

Useful profiles:

• workspace - filesystem, git, context7, sqlite, with safe defaults.
• research - web/paper/documentation discovery tools.
• data - database inspection with conservative mutation policy.
• mcp-dev - MCP authoring, inspection, and client config generation.
• deploy-readonly - explicit infrastructure inspection profile.

Gateway helper commands:

pdm run rosetta gateway explain
pdm run rosetta gateway tools
pdm run rosetta gateway resources
pdm run rosetta gateway prompts