# Agentic MCP Solution

A FastAPI + CLI backend that exposes a set of external services — Gmail, Google Docs, Google Sheets, Google Calendar, Google Chat, Postgres, and MongoDB — as MCP-style tools that an LLM (Claude or Gemini) can invoke through a single, consistent interface.

## Architecture

- `src/core/mcp_base.py` / `mcp_manager.py` — the shared MCP server abstraction and a manager that discovers and dispatches to whichever servers are enabled in `config/config.yaml`.
- `src/core/google_auth.py` — OAuth flow for Google Workspace access.
- `src/mcp_servers/` — one module per integration (`gmail_server.py`, `gdocs_server.py`, `gsheets_server.py`, `gcalendar_server.py`, `gchat_server.py`, `postgres_server.py`, `mongodb_server.py`, `claude_server.py`, `gemini_server.py`), each implementing the same base interface so new integrations plug in without touching the API or CLI layer.
- `src/api/main.py` — the FastAPI app exposing these capabilities over HTTP.
- `src/cli/main.py` — a Click-based CLI for the same capabilities, useful for local testing without standing up the API.

## Verified working

The FastAPI app builds correctly (`from src.api.main import app` succeeds) and every MCP server module imports cleanly. The CLI runs and exposes:

```
Commands:
  capabilities  List all available capabilities
  docs          Google Docs operations
  execute       Execute a capability
  gmail         Gmail operations
  health        Check health status of all MCP servers
  task          Execute a complex task
```

An example end-to-end workflow this architecture supports: inspect Gmail messages → analyze the contents with Claude or Gemini → generate a structured report → create or update a Google Doc with the result, all through the same MCP tool-calling interface.

## Getting started

Requires Python 3.13+ (the `websockets` version this depends on uses `typing.Self`, which needs 3.11+; the project pins 3.13).

```bash
uv sync   # or: pip install -e .
cp .env.example .env   # fill in your API keys
```

Google Workspace access needs OAuth credentials placed at `credentials/credentials.json` (gitignored — not something to commit).

```bash
uv run agentic-api            # start the FastAPI server
uv run agentic-cli capabilities
uv run agentic-cli health
```

## Status & limitations

`gemini_server.py` currently uses `google.generativeai`, which Google has fully deprecated in favor of `google.genai` — it still works but should be migrated. There's no real test coverage yet (`tests/` has the pytest configuration wired up in `pyproject.toml` but no test bodies). Rate limiting and API-key auth are present in `config.yaml` but off by default (`api_key_required: false`) — worth turning on before exposing this beyond local use.

## License

MIT — see [LICENSE](LICENSE).