raku-mcp-sdk: 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 Overview

Raku implementation of the Model Context Protocol (MCP) SDK. MCP is an open standard that allows AI models to interact with external data and tools. This SDK enables building MCP servers and clients in Raku to integrate with LLM applications like Claude Desktop.

Build Commands

make all              # Full pipeline: dependencies + build + test
make build            # Validate metadata and precompile modules
make test             # Run complete test suite
make test-verbose     # Run tests with verbose output
make test-file FILE=t/03-builders.rakutest  # Run specific test
make lint             # Run syntax and META6.json validation
make check            # Run lint and tests together
make coverage         # Generate test coverage report
make benchmark        # Run performance benchmarks
make run-example EXAMPLE=simple-server      # Run example server
make repl             # Start REPL with project loaded
make benchmark        # Run performance benchmarks
make stress           # Run stress tests

Environment: V=1 for verbose output, NO_COLOR=1 to disable colors.

Architecture

MCP.rakumod (main entry point, re-exports all public API)
├── MCP::Types        # Protocol types: Content, Tool, Resource, Prompt, Capabilities
├── MCP::JSONRPC      # JSON-RPC 2.0 message types and parsing
├── MCP::Server       # Server initialization, request dispatch, lifecycle
├── MCP::Client       # Client initialization, sampling support
├── MCP::Server::Tool/Resource/Prompt  # Fluent builders for primitives
├── MCP::Transport::Base/Stdio/StreamableHTTP/SSE  # Transport layer
└── MCP::OAuth / OAuth::Client / OAuth::Server  # OAuth 2.1 authorization

Protocol: JSON-RPC 2.0 over Stdio, Streamable HTTP, or Legacy SSE. Targets MCP spec 2025-11-25.

Key Patterns

Builder Pattern for tools, resources, and prompts:

my $tool = tool()
    .name('add')
    .description('Add two numbers')
    .input-schema(%schema)
    .handler(-> :%params { $params<a> + $params<b> })
    .build;