genesis-mcp: Instructions file for Claude Code

CLAUDE.md

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

Commands

# Install (editable, with dev deps)
pip install -e ".[dev]"

# Run the MCP server
python -m genesis.server

# Run all tests
pytest tests/

# Run a single test file
pytest tests/test_validator.py -v

Architecture

Genesis MCP is a self-extending MCP server. The key design: it uses the low-level mcp.Server class (not FastMCP) so that list_tools and call_tool are implemented as dynamic handlers that read from the in-memory registry at call time. This is what makes hot-loading possible without a server restart.

Important: Genesis does not call any LLM API server-side. Code generation runs on the host LLM (Claude Desktop, Cursor, etc.). Genesis only assembles a prompt and accepts the resulting code back through register_tool.

Data flow for tool creation

User asks Claude to make a tool
  → host LLM calls meta_tools.create_tool(description)
      → generator.build_generation_prompt()        # returns a prompt STRING; no API call
  → host LLM reads the prompt, generates Python code locally
  → host LLM calls meta_tools.register_tool(code=...)
      → validator.validate()                        # 8 checks, fail-fast
      → write generated_tools/<name>.py
      → loader.load_tool_file()                     # importlib dynamic load
      → registry.register()                         # in-memory + tools_manifest.json

The trust boundary is register_tool: any string that passes validator.validate() is loaded into the live server process.

Key files

File	Responsibility
genesis/server.py	Entry point. Low-level MCP server with dynamic dispatch.
genesis/meta_tools.py	The 6 built-in meta-tools (create_tool, register_tool, list_tools, delete_tool, update_tool, describe_tool). META_TOOL_SCHEMAS is read by server at boot.
genesis/generator.py	Builds the natural-language prompt that the host LLM consumes. No API calls.
genesis/validator.py	AST-based checks: syntax, imports, forbidden calls, forbidden names (reflection), structure, schema, uniqueness, side effects.
genesis/registry.py	In-memory {name: ToolEntry} dict. Persists to tools_manifest.json.
genesis/loader.py	importlib.util dynamic loading. Raises LoadError on all failure modes.
genesis/config.py	Singleton config loaded from config.yaml. Also calls load_dotenv for future-compat, but no subsystem reads env vars in v0.1.