# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Common Development Commands
### Building and Running
- `npm run build` - Compile TypeScript to JavaScript in the dist/ directory
- `npm run dev` - Start TypeScript compiler in watch mode for development
- `npm start` - Run the compiled server from dist/plantuml-mcp-server.js
- `make build` - Clean and build the project (preferred)
- `make run` - Build and run the server with proper setup
- `make dev` - Run TypeScript in watch mode using Makefile
### Testing
- `make test-mcp` - Test using mcptools CLI with sample PlantUML diagrams (comprehensive test including C4 diagrams)
- `make test` - Test server functionality with background process
### Setup and Installation
- `make install` - Install npm dependencies with Node.js version check
- `make setup` - Full setup including install, build, and Claude Code configuration
- `make setup-claude` - Show Claude Code MCP configuration instructions
## Project Architecture
### Single-File MCP Server
This is a Model Context Protocol (MCP) server that provides PlantUML diagram generation capabilities. The project follows a single-file architecture pattern with all core logic in `src/plantuml-mcp-server.ts:22-216`.
**Main Components:**
- `src/plantuml-mcp-server.ts` - Complete MCP server implementation with PlantUML capabilities
- `dist/` - Compiled JavaScript output directory (TypeScript target: ES2022, module: ESNext)
- `Makefile` - Comprehensive build and development workflow management
- `package.json` - Configured as ESM module with bin entry for npx support
### MCP Tools Implementation
The server implements three MCP tools via the `PlantUMLMCPServer` class:
1. **`generate_plantuml_diagram`** (src/plantuml-mcp-server.ts:93-144)
- Generates PlantUML diagrams and returns embeddable URLs
- Supports SVG/PNG formats
- Validates server accessibility with fetch requests
- Returns markdown embed code
2. **`encode_plantuml`** (src/plantuml-mcp-server.ts:146-175)
- Encodes PlantUML code for URL usage using plantuml-encoder library
3. **`decode_plantuml`** (src/plantuml-mcp-server.ts:177-206)
- Decodes encoded PlantUML strings back to source code
### Dependencies and Configuration
- Uses `@modelcontextprotocol/sdk` for MCP protocol implementation
- Uses `plantuml-encoder` library for encoding/decoding (src/plantuml-mcp-server.ts:11-17)
- `PLANTUML_SERVER_URL` environment variable (defaults to https://www.plantuml.com/plantuml)
- Requires Node.js 18+ (specified in package.json engines)
- Server runs on stdio transport for MCP communication
### Development Workflow
The project uses TypeScript with strict type checking. The comprehensive Makefile provides all necessary commands for development, testing, and deployment. The server can be installed via `npx plantuml-mcp-server` after publishing to npm, or run locally via `make run`.
- For this project always use public planuml server 'https://www.plantuml.com/plantuml' for rendering diagrams
