init

2026-06-24 11:19:17 +08:00
commit b56d7c80dd
9 changed files with 1075 additions and 0 deletions
@@ -0,0 +1,55 @@
+# 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.