# GTD MCP Server: Python FastMCP on Databricks Apps

A practical, self-learning **Model Context Protocol (MCP) server tutorial** built
with Python, FastMCP, FastAPI, and Databricks Apps. The project implements a
Getting Things Done assistant with typed MCP tools for tasks, projects, inbox
capture, next actions, and statistics.

Run the same MCP server locally with Codex and SQLite, or deploy it as a custom
Databricks App backed by a Unity Catalog Delta table and SQL warehouse. The
server supports both stdio and Streamable HTTP at `/mcp`, and can be attached to
Databricks AI Playground through its Tools panel.

## What You Will Learn

- how to build an MCP server in Python with FastMCP,
- how MCP tools, schemas, transports, and structured responses work,
- how to connect a local MCP server to Codex,
- how to deploy an MCP server with Databricks Apps,
- how to use Databricks App resources, service-principal authentication,
  Unity Catalog, Delta tables, and a SQL warehouse,
- how to keep domain logic portable between SQLite and Databricks storage.

Start with [QUICKSTART.md](QUICKSTART.md) for setup and deployment. Use
[ARCHITECTURE.md](ARCHITECTURE.md) as the complete workshop and extension guide.

Keywords: Model Context Protocol, MCP server, Python MCP, FastMCP, FastAPI,
Databricks Apps, Databricks AI Playground, Codex MCP, Unity Catalog, Delta Lake,
SQL Warehouse, AI agents, GTD assistant.

The operational code lives in `src/`; setup notebooks and client integration
guides live in `docs/`.

## Repository Map

```text
gtd-mcp-server/
├── README.md                 # how to navigate and work with this repo
├── QUICKSTART.md             # local and Databricks Apps startup paths
├── ARCHITECTURE.md
├── LICENSE
├── pyproject.toml            # uv project metadata
├── uv.lock                   # locked local dependency set
├── src/                      # server package and Databricks app config
└── docs/
    ├── databricks_setup_storage.py
    ├── databricks_playground.md
    └── local_llm_ide.md
```

Local runs create a SQLite database at `.local/gtd.sqlite3` by default.
Databricks Apps use Delta storage.

## Main Concepts

- `src/gtd_mcp_server/server.py`: FastMCP tools, FastAPI routes, launchers.
- `src/gtd_mcp_server/storage.py`: storage abstraction, SQLite backend, Delta backend.
- `src/gtd_mcp_server/models.py`: GTD task, project, inbox, and stats models.
- `src/app.yaml`: Databricks Apps startup command.
- `src/requirements.txt`: dependencies installed by Databricks Apps.
- `pyproject.toml`: local `uv` project metadata.
- `uv.lock`: locked local dependency set.
- `docs/databricks_setup_storage.py`: Databricks notebook that creates the Unity Catalog
  catalog, schema, and Delta table.
- `docs/databricks_playground.md`: how to attach the deployed app through the
  Playground Tools panel.
- `docs/local_llm_ide.md`: how to connect the local server to Codex.

## Storage Modes

Local default:

```bash
GTD_STORAGE_BACKEND=sqlite
GTD_SQLITE_PATH=.local/gtd.sqlite3
```

Databricks Apps:

```bash
GTD_STORAGE_BACKEND=delta
GTD_DELTA_TABLE=gtd_mcp.app.gtd_mcp_records
DATABRICKS_WAREHOUSE_ID=<warehouse-id>
DATABRICKS_HOST=<injected-by-databricks-apps>
```

Before deployment, attach a SQL warehouse resource with key `sql-warehouse`
and a UC table resource with key `table`. `app.yaml` maps both resources into
environment variables with `valueFrom`; Databricks Apps injects
`DATABRICKS_HOST` and service-principal credentials.

Before deploying on Databricks, run `docs/databricks_setup_storage.py` as a
Databricks notebook. It creates the `gtd_mcp` catalog, `app` schema, and
`gtd_mcp_records` Delta table used by the server.

When `DATABRICKS_APP_NAME` is present and `GTD_STORAGE_BACKEND` is unset, the
server assumes `delta`.

Databricks Apps installs `requirements.txt` and starts the command from `app.yaml`:

```bash
uvicorn gtd_mcp_server.server:app --host 0.0.0.0 --port $DATABRICKS_APP_PORT
```

## Daily Workflow

From this folder:

```bash
uv sync
uv run gtd-mcp-server
```

Then use:

- REST health check: `http://localhost:8000/health`
- MCP streamable HTTP endpoint: `http://localhost:8000/mcp`
- OpenAPI docs for the helper REST API: `http://localhost:8000/docs`

Use `/mcp` from an MCP client.