dad8d41e46
- 优化工具列表显示：工具名称优先显示，描述悬停提示 - 集成OpenRouter支持：400+模型一键访问 - 改进模型选择界面：支持搜索过滤和分类显示 - 自动同步新提供商配置 - 版本升级至0.1.7 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
170 lines
6.2 KiB
Markdown
170 lines
6.2 KiB
Markdown
# 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
|
|
- `renderer/package.json` - Frontend dependencies and scripts
|
|
|
|
### Core Architecture
|
|
|
|
- `src/extension.ts` - VSCode extension entry point
|
|
- `service/src/main.ts` - Service WebSocket server
|
|
- `service/src/common/router.ts` - Request routing system
|
|
- `renderer/src/api/message-bridge.ts` - Cross-platform communication
|
|
- `service/src/mcp/client.service.ts` - MCP client implementation
|