Metadata-Version: 2.4
Name: agensflow-mcp
Version: 0.1.0
Summary: AgensFlow MCP — learned coordination substrate for coding-agent loops
Author: Nicole Koenigstein
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: alembic>=1.13
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: cryptography>=43.0
Requires-Dist: fastapi>=0.115
Requires-Dist: fastmcp>=0.4
Requires-Dist: greenlet>=3.0
Requires-Dist: httpx>=0.27
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: pydantic>=2.5
Requires-Dist: python-jose[cryptography]>=3.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: structlog>=24.4
Requires-Dist: tenacity>=9.0
Requires-Dist: uvicorn[standard]>=0.32
Provides-Extra: dev
Requires-Dist: asgi-lifespan>=2.1; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: ipython>=8.0; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# agensflow-mcp

Learned coordination substrate for coding-agent and MAS loops. Apache-2.0.
Self-host, or use the hosted service.

## What this is

AgensFlow MCP is a policy server. For each task signature your agent sees, it
learns which sub-agent, model, and effort setting produces the best outcome —
where "best" is a weighted trade-off of quality, cost, latency, and token
budget you configure.

Under the hood: a per-signature UCB1 bandit with Welford-online variance,
Anthropic cache-aware pricing, tenant isolation, and BYOK judge orchestration.

Two integration paths cover essentially every agent shape:

- **Framework adapters** — LangGraph, CrewAI, or any Runnable-shaped MAS
  framework plug in via [`agensflow-langgraph`](https://github.com/AgensFlow-ai/agensflow-langgraph):
  one decorator per node, per-node model pool, one line to record reward. The
  adapter owns judge orchestration; the server records decisions and updates
  the policy.
- **Direct MCP integration** — Claude Code / codex hook the server via
  PreToolUse + SubagentStop hooks. The server orchestrates a BYOK
  single-model or 3-panel cross-family judge over `POST /judge/relative`.

## Install

```bash
pip install agensflow-mcp
```

Requires Python ≥ 3.11. Postgres is recommended for production; SQLite works
out-of-the-box for local dev.

## Run the server

```bash
# Local dev (in-process SQLite, no external deps)
agensflow-mcp serve
# → http://localhost:8000/health
# → http://localhost:8000/docs      (OpenAPI schema explorer)
# → http://localhost:8000/mcp/sse   (FastMCP endpoint)

# Full stack with Postgres via Docker
docker run -d --name agensflow-postgres \
  -e POSTGRES_PASSWORD=agf -p 5432:5432 postgres:16
AGF_DATABASE_URL=postgresql+psycopg://postgres:agf@localhost:5432/agensflow \
  agensflow-mcp serve
```

Once up, verify:

```bash
curl -s http://localhost:8000/health
# → {"status":"ok","version":"..."}
```

## Architecture

```
      Framework                Claude Code
      adapter                  / codex hooks
     (LangGraph, CrewAI, ...)      │
        │                          │
        └─────────┬────────────────┘
                  ▼
         ┌──────────────────────────────────────────┐
         │ HTTP + MCP surface                       │
         │                                          │
         │  /route            /judge/relative       │
         │  /record           /policy/{me,id}       │
         │  /auth/anonymous   /auth/byok            │
         │  /langgraph/policy/{select,import,       │
         │                     export}              │
         │  /langgraph/decision/execute             │
         │  /langgraph/reward/submit                │
         │  /langgraph/decisions                    │
         │                                          │
         │  /mcp/sse           (FastMCP tools)      │
         └────────────────────┬─────────────────────┘
                              ▼
                    ┌───────────────────┐
                    │ Substrate engine  │
                    │   folding · UCB1  │
                    │   Welford         │
                    │   reward · pricing│
                    └─────────┬─────────┘
                              ▼
                     Postgres / SQLite
```

## Tier model

| Tier | Package | What you get |
|---|---|---|
| **Free** | `agensflow-mcp` (public, PyPI) | UCB1 substrate, reward formula `w_q·quality − w_c·cost − w_t·tokens − w_l·latency`, tenant isolation, all HTTP endpoints (`/route`, `/record`, `/judge/relative`, `/langgraph/*`, `/auth/*`, `/policy/*`), 3-judge cross-family panel over OpenRouter (BYOK), extension plugin discovery for overlays |
| **Enterprise** | Private overlay (not on PyPI) | Everything above + private-tier observability signals and reward extensions. Auto-loaded via importlib entry-point when installed |

The free tier is fully functional standalone. Enterprise is an overlay you
install alongside; the server auto-discovers it at boot and mounts the
additional routes + companion tables. Nothing on the free tier depends on the
enterprise package being present.

## Learn more

- **Integration guide (LangGraph adapter)** — [`agensflow-langgraph` docs](https://github.com/AgensFlow-ai/agensflow-langgraph/blob/main/docs/integration.md)
- **API reference** — boot the server and open [`http://localhost:8000/docs`](http://localhost:8000/docs)
- **Privacy & data handling** — [PRIVACY.md](PRIVACY.md)
- **Self-hosted deployment** — [DEPLOY.md](DEPLOY.md)

## License

Apache-2.0
