mcp-server/CLAUDE.md

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, 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.

# 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.