Metadata-Version: 2.4
Name: ba-agent-mcp
Version: 0.2.0
Summary: MCP server exposing the Modern-Expo virtual Business Analyst Knowledge Base (read/derive tools).
Author: Modern-Expo
Keywords: mcp,model-context-protocol,business-analyst,knowledge-base,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2
Requires-Dist: pypdf>=4
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

# ba-agent-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes the Modern-Expo
virtual **Business Analyst Knowledge Base** as a small set of **read / derive**
tools. It never writes to SUPPA Docs or the Knowledge Base and is deliberately
kept off the governed write path — authoring documents goes through the
human-gated `business-analyst` skill, not this server.

## Install

```bash
uvx ba-agent-mcp          # run on demand in an isolated environment (recommended)
# or
pip install ba-agent-mcp  # then run: ba-agent-mcp
```

## Credentials — you supply your own

**This package ships no credentials.** Each user provides their **own** keys and
their **own** SUPPA identity. Nothing is ever read from the MCP client JSON
config; secrets are resolved from the environment, in this order:

1. real environment variables in the launching shell, then
2. an explicit env file at `$BA_AGENT_ENV_FILE`, then
3. `~/.ba-agent/.env`

```bash
# ~/.ba-agent/.env   (or export these in your shell)
SUPABASE_URL=https://<your-project>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=...        # or SUPABASE_ANON_KEY for read-only
SUPPA_API_KEY=...                    # your own SUPPA identity (or SUPPA_TOKEN)
GEMINI_API_KEY=...                   # optional — enables hybrid (vector) search
FIGMA_TOKEN=...                      # optional — enables analyze_figma
```

> Never put any secret in the MCP client JSON. A tool whose credentials are
> absent returns a clear, structured error instead of failing the server, so you
> can add capabilities incrementally.

## Connect (any MCP client)

```json
{
  "mcpServers": {
    "ba-agent": {
      "command": "uvx",
      "args": ["ba-agent-mcp"],
      "env": { "BA_AGENT_ENV_FILE": "/absolute/path/to/your/.env" }
    }
  }
}
```

## Tools

| Tool | Returns |
| --- | --- |
| `kb_search` | Ranked KB hits with provenance (title, breadcrumb, SUPPA anchor, `data_class`). |
| `kb_assemble_context` | A cited grounding block for a question + coverage + strictest `data_class`. |
| `kb_assemble_corpus` | The whole project corpus grouped by document, for cross-corpus analysis. |
| `kb_list_docs` | Inventory of governed documents in a project (reads SUPPA under your own identity). |
| `analyze_figma` | A structured design profile of a Figma file (requires `FIGMA_TOKEN`). |

## Data governance

The KB read tools connect with the Supabase service-role key, which bypasses
row-level security, so they **fail closed at the application layer**: any chunk
that is not explicitly `data_class = 'internal'` is excluded from results.
Consequence — **`client`-classed content is not readable over MCP**. The
append-only logs never contain document bodies, only ids, hashes, identity, and
HTTP status.

---

Proprietary — Modern-Expo internal tooling. All rights reserved.
