CLAUDE.md · LSTM-Kirigaya/openmcp-client

Sections

1. Development Commands
2. Architecture Overview
3. Development Workflow
4. Important Files
5. Development Reminders

First lines (shown under the repo's Apache-2.0 license)

# CLAUDE.md

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

## Development Commands

### Setup and Installation
```bash
npm run setup                 # Install dependencies and prepare OCR resources
```

### Development
```bash
npm run serve                 # Start all services in development mode (uses Turbo)
npm run build                 # Build all modules
npm run build:all             # Build all modules (alias)
npm run build:electron        # Build only Electron app
```

### Service Development
```bash
cd service
npm run serve                 # Start service with hot reload (nodemon + tsx)
npm run build                 # Compile TypeScript to dist/
npm run debug                 # Start with Node.js inspector
npm run typecheck             # Type checking without emit
```

### Renderer Development
```bash
cd renderer
npm run serve                 # Start Vite dev server
npm run build                 # Build for production
npm run serve:website         # Start in website mode
npm run type-check            # Vue TypeScript checking
```

### VSCode Extension
```bash
npm run vscode:prepublish     # Prepare for VSCode publishing (Rollup build)
npm run compile               # Compile TypeScript
npm run watch                 # Watch mode compilation
vsce package                  # Create VSIX package for distribution
vsce publish                  # Publish to VSCode Marketplace (requires auth)
```

### Quality Assurance
```bash
npm run lint                  # ESLint for TypeScript files
npm run pretest               # Run compile and lint
npm run test                  # Run tests
```

## Architecture Overview

### Multi-Module Structure
OpenMCP follows a **layered modular architecture** with three main deployment targets:

1. **VSCode Extension** (`src/extension.ts`) - IDE integration
2. **Service Layer** (`service/`) - Node.js backend handling MCP protocol
3. **Renderer Layer** (`renderer/`) - Vue.js frontend for UI

### Key Architectural Patterns

#### Message Bridge Communication
The system uses a **message bridge pattern** for cross-platform communication:
- **VSCode**: Uses `vscode.postMessage` API
- **Electron**: Uses IPC communication
- **Web**: Uses WebSocket connections
- **Node.js**: Uses EventEmitter for SDK mode

All communication flows through `MessageBridge` class in `renderer/src/api/message-bridge.ts`.

#### MCP Client Management
- **Connection Management**: `service/src/mcp/connect.service.ts` handles multiple MCP server connections
- **Client Pooling**: `clientMap` maintains active MCP client instances with UUID-based identification
- **Transport Abstraction**: Supports STDIO, SSE, and StreamableHTTP transports
- **Auto-reconnection**: `McpServerConnectMonitor` handles connection monitoring

#### Request/Response Flow
```
Frontend (Vue) → MessageBridge → Service Router → MCP Controllers → MCP SDK → External MCP Servers
```

### Important Service Patterns

#### Preprocessing Commands
`service/src/mcp/connect.service.ts` includes **automatic environment setup**:
- Python projects: Auto-runs `uv sync` and installs MCP CLI
- Node.js projects: Auto-runs `npm install` if node_modules missing
- Path resolution: Handles `~/` home directory expansion

#### OCR Integration
Built-in OCR using Tesseract.js:
- Images from MCP responses are automatically processed
- Base64 images saved to temp files and queued for OCR
- Results delivered via worker threads

### Frontend Architecture (Vue 3)

#### State Management
- **Panel System**: Tab-based interface in `renderer/src/components/main-panel/`
- **Reactive Connections**: MCP connection state managed reactively
- **Multi-language**: Vue i18n with support for 9 languages

#### Core Components
- **Chat Interface**: `main-panel/chat/` - LLM interaction with MCP tools
- **Tool Testing**: `main-panel/tool/` - Direct MCP tool invocation
- **Resource Browser**: `main-panel/resource/` - MCP resource exploration
- **Prompt Manager**: `main-panel/prompt/` - System prompt templates

### Build System

#### Turbo Monorepo
Uses Turbo for coordinated builds across modules:
- **Dependency ordering**: Renderer builds before Electron
- **Parallel execution**: Service and Renderer can build concurrently
- **Task caching**: Disabled for development iterations

#### Rollup Configuration
VSCode extension uses Rollup for optimal bundling:
- **ES modules**: Output as ESM format
- **External dependencies**: VSCode API marked as external
- **TypeScript**: Direct compilation without webpack

## Development Workflow

### Adding New MCP Features
1. **Service Layer**: Add controller in `service/src/mcp/`
2. **Router Registration**: Add to `ModuleControllers` in `service/src/common/router.ts`
3. **Frontend Integration**: Add API calls in `renderer/src/api/`
4. **UI Components**: Create components in `renderer/src/components/`

### Testing MCP Servers
1. **Connection**: Configure in connection panel (STDIO/SSE/HTTP)
2. **Validation**: Test tools/resources in respective panels
3. **Integration**: Verify LLM interaction in chat interface

### Packaging VSCode Extension

1. **Build Dependencies**: Run `npm run build` to build all modules
2. **Prepare Extension**: Run `npm run vscode:prepublish` to bundle extension code
3. **Create Package**: Run `vsce package` to generate `.vsix` file
4. **Install Locally**: Use `code --install-extension openmcp-x.x.x.vsix` for testing
5. **Publish**: Run `vsce publish` (requires marketplace publisher account)

### Platform-Specific Considerations

- **VSCode**: Uses webview API, limited to extension context
- **Electron**: Full desktop app capabilities, local service spawning
- **Web**: Requires external service, WebSocket limitations
- **SDK**: Embedded in other Node.js applications

## Important Files

### Configuration

- `turbo.json` - Monorepo build orchestration
- `rollup.config.js` - VSCode extension bundling
- `service/package.json` - Backend dependencies and scripts