cf-mcp AGENTS.md

CLAUDE.md

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

Project Overview

CF::MCP is a Ruby gem that implements an MCP (Model Context Protocol) server for the Cute Framework, a C/C++ 2D game framework. It indexes header files, extracts documentation from comments, and provides search functionality for functions, structs, and enums.

Commands

# Install dependencies
bin/setup

# Run all tests
rake test

# Run a single test file
ruby -Ilib:test test/cf/mcp/parser_test.rb

# Run a specific test method
ruby -Ilib:test test/cf/mcp/parser_test.rb --name test_parse_function_doc

# Lint code with Standard Ruby
rake standard

# Auto-fix linting issues
rake standard:fix

# Run tests, lint, and generate manifest (default task)
rake

# Start interactive console
bin/console

# Install gem locally
bundle exec rake install

# Create git tag for current version
rake tag

# Create tag and push to origin
rake release:tag

# Release to RubyGems (creates tag, builds gem, pushes)
rake release

CLI Usage

# STDIO mode (for Claude Desktop integration)
cf-mcp stdio --root ~/Work/GitHub/pusewicz/cute_framework

# HTTP mode (web UI at /, MCP endpoint at /http, port 9292)
cf-mcp http --port 9292 --root /path/to/cute_framework

# Download headers from GitHub automatically
cf-mcp stdio --download

Architecture

lib/cf/mcp/
├── cli.rb              # CLI with stdio/http modes
├── server.rb           # MCP server setup, Server and HTTPServer classes
├── parser.rb           # Header file parser (extracts @function, @struct, @enum docs)
├── index.rb            # In-memory search index with relevance scoring
├── downloader.rb       # GitHub header downloader with ZIP extraction
├── models/
│   ├── doc_item.rb     # Base model with search/relevance scoring
│   ├── function_doc.rb # FunctionDoc with signature, params, return
│   ├── struct_doc.rb   # StructDoc with members
│   └── enum_doc.rb     # EnumDoc with entries
├── tools/
│   ├── search_tool.rb      # search - search all types with optional type/category filters
│   ├── list_category.rb    # list_category
│   └── get_details.rb      # get_details - full docs by name
└── templates/          # Web UI for HTTP mode
    ├── index.erb
    ├── style.css
    └── script.js