mcp-modal: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

mcp-modal is an MCP (Model Context Protocol) server that exposes 12 tools and 4 prompts for managing Modal (apps, containers, volumes, secrets) and for deploying/running Modal apps. It is published to PyPI as mcp-modal and is meant to be launched by MCP clients via uvx mcp-modal.

Common commands

# Install/sync deps (creates .venv/)
uv sync

# Run the server locally (stdio transport — for testing it speaks MCP)
uv run mcp-modal

# Build the wheel/sdist (hatchling backend)
uv build

# Smoke-test against a real Modal account — the server shells out to the local
# `modal` CLI, so credentials must already be configured:
modal setup            # one-time login → ~/.modal.toml
modal profile current  # verify which workspace you're using

There is no test suite, linter config, or CI in this repo. Don't claim a change is verified by tests — exercise it by running the server against a real Modal account, or by inspecting the constructed CLI commands in the returned command field.

Architecture

Module layout

src/mcp_modal/
  server.py      assembly point: imports the pieces, re-exports the public names, main()
  app.py         the FastMCP instance (`mcp`), `logger`, and _read_only/_mutating
  command.py     argv helpers (_add_env, _uv_prefixed, path allowlist) + the two runners
  output.py      output caps and the response envelope (handle_json_response, json_listing…)
  logsearch.py   pure log-text logic: grep_lines, filter_log_lines, cap_blocks, window checks
  billing.py     pure cost math: Decimal helpers, _row_field aliases, group_costs, cost_movers
  prompts.py     the 4 @mcp.prompt() workflows
  tools/         the 12 @mcp.tool() functions, one module per group
    deploy.py resources.py logs.py apps.py volumes.py secrets.py costs.py

The dependency graph runs strictly one way: app → command → output → logsearch → tools/prompts → server, with billing depending on nothing but the stdlib. (output imports command because json_listing runs the command itself, and logsearch imports output for the character budget cap_blocks spends.) Nothing under tools/ is imported by a support module, and app.py imports nothing from the package — keep it that way and there are no cycles to reason about.