Metadata-Version: 2.1
Name: rosetta-mcp-workspace
Version: 0.4.0
Summary: Observable agent workspace control plane for MCP servers, FastMCP gateways, packs, profiles, skills, prompts, resources, and client syncs.
Keywords: mcp,fastmcp,langchain,langgraph,agents,llm
Author: William R. Astley
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/pr1m8/rosetta-mcp
Project-URL: Repository, https://github.com/pr1m8/rosetta-mcp
Project-URL: Documentation, https://rosetta-mcp.readthedocs.io/
Project-URL: Issues, https://github.com/pr1m8/rosetta-mcp/issues
Requires-Python: >=3.13
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: typer>=0.12.5
Requires-Dist: rich>=13.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: platformdirs>=4.3.0
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "api"
Provides-Extra: db
Requires-Dist: sqlalchemy[asyncio]>=2.0.36; extra == "db"
Requires-Dist: asyncpg>=0.30.0; extra == "db"
Requires-Dist: psycopg[binary]>=3.2.0; extra == "db"
Requires-Dist: alembic>=1.14.0; extra == "db"
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: langchain
Requires-Dist: langchain>=0.3.0; extra == "langchain"
Requires-Dist: langgraph>=0.2.0; extra == "langchain"
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == "langchain"
Requires-Dist: langchain-openai>=0.3.0; extra == "langchain"
Provides-Extra: observability
Requires-Dist: structlog>=25.0.0; extra == "observability"
Requires-Dist: opentelemetry-api>=1.30.0; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.30.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp>=1.30.0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.51b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-asgi>=0.51b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.51b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.51b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0; extra == "observability"
Requires-Dist: prometheus-client>=0.21.0; extra == "observability"
Provides-Extra: docs
Requires-Dist: sphinx>=8.2.0; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser>=4.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == "release"
Requires-Dist: twine>=6.0.0; extra == "release"
Provides-Extra: all
Requires-Dist: rosetta-mcp-workspace[api,db,langchain,mcp,observability]; extra == "all"
Description-Content-Type: text/markdown

# 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`:

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

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

For local development:

```bash
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:

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

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

## Validate

Fast syntax and scaffold checks:

```bash
make verify-fast
```

Full validation after installing all groups:

```bash
make verify
```

## CLI examples

```bash
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:

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

For local live preview:

```bash
pdm run sphinx-autobuild docs docs/_build/html
```

Read the Docs configuration lives in [.readthedocs.yaml](.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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](docs/graph-runtime.md).

## 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](docs/release.md).

## 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:

```bash
make serve-api
# or
pdm run rosetta api serve
```

Run the gateway in the foreground:

```bash
make serve-gateway
```

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

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

Smoke test API endpoints:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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:

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