56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
`spark-executor-mcp` is a Python 3.12+ service that wraps Spark-related operations as a **Model Context Protocol (MCP)** server, exposed via HTTP through FastAPI. The MCP layer is built on top of [`fastapi-mcp`](https://github.com/tadata-org/fastapi_mcp), which auto-discovers FastAPI routes and exposes them as MCP tools.
|
|
|
|
## Common Commands
|
|
|
|
The project uses `uv` for dependency management. Dependencies are pinned in `pyproject.toml` and `uv.lock`. A virtualenv already exists at `.venv/`. PyPI index is configured to the Tsinghua mirror in `pyproject.toml`.
|
|
|
|
```bash
|
|
# Install/sync dependencies
|
|
uv sync
|
|
|
|
# Run the server (binds 0.0.0.0:8000)
|
|
uv run main.py
|
|
|
|
# Or activate the venv and run directly
|
|
source .venv/bin/activate
|
|
python main.py
|
|
```
|
|
|
|
Once running, the MCP endpoint is mounted at `http://localhost:8000/spark-executor-mcp`. The `spark_executor` app's own routes (e.g. `/health`) remain available at the root.
|
|
|
|
There is currently no test suite, linter configuration, or CI config in the repository.
|
|
|
|
## Architecture
|
|
|
|
The codebase is small and intentionally layered — the goal is to add new "tool" FastAPI sub-apps and have them be auto-exposed as MCP.
|
|
|
|
```
|
|
main.py # Root FastAPI app; lifespan wires in the MCP server
|
|
common/
|
|
factory.py # init_mcp_server(app) -> FastApiMCP wrapper
|
|
logging.py # loguru logger, level=DEBUG to stderr
|
|
spark_executor/
|
|
__init__.py # Re-exports `app`
|
|
server.py # Spark Executor FastAPI app (the MCP tool surface)
|
|
```
|
|
|
|
**How a request flows:**
|
|
|
|
1. `main.py` creates the root `FastAPI(title="Main App")` and registers an `asynccontextmanager` `lifespan`.
|
|
2. At startup, the lifespan calls `init_mcp_server(spark_executor_app)` (`common/factory.py`) which returns a `FastApiMCP` instance bound to the spark executor's FastAPI app.
|
|
3. That `FastApiMCP` is mounted onto the root app at `/spark-executor-mcp` via `mount_http(...)`. `fastapi-mcp` inspects the spark executor's routes and registers each one as an MCP tool.
|
|
4. To add new MCP tools, define new routes on the `app` in `spark_executor/server.py` (or create a new sub-package and mount it the same way in `main.py`'s lifespan) — they will be picked up automatically.
|
|
|
|
**Key conventions:**
|
|
|
|
- All modules include the file header `# coding=utf-8` plus a `@Time` / `@Author` docstring. Match this when adding new files.
|
|
- `common/logging.py` configures a single process-wide `loguru` logger and removes the default handler. Import `from common.logging import logger` rather than creating new loggers.
|
|
- `spark_executor/__init__.py` re-exports `app` so callers can `from spark_executor import app` — keep this re-export when adding to the package.
|
|
- The `FastApiMCP` instance is created per-app in the lifespan; do not cache it at module import time.
|