CLAUDE.md•3.67 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is an MCP (Model Context Protocol) Hub server that acts as a proxy/aggregator for multiple MCP servers. It bypasses tool limitations in AI assistants (especially Cursor's 40-tool limit) and provides a unified interface to multiple MCP servers.
## Development Commands
### Build and Run
```bash
# Install dependencies
pnpm install
# Build TypeScript to JavaScript
pnpm build
# Run the server (after building)
pnpm start
# Build and run in one command
pnpm dev
```
### Development Workflow
```bash
# For testing changes locally with npx
npm link # Creates a global link to the local package
npx mcp-hub-mcp # Test the linked version
# To unlink after testing
npm unlink -g mcp-hub-mcp
```
### Release Process
- Uses semantic-release with Conventional Commits
- Commits should follow: `type(scope): description`
- Types: feat, fix, docs, style, refactor, perf, test, chore
- Breaking changes: add `!` after type or `BREAKING CHANGE:` in body
- Releases are automated via GitHub Actions on the main branch
## Architecture
### Core Components
1. **src/index.ts** - Entry point that creates the MCP server with three tools:
- `list-all-tools`: Lists all available tools from connected servers
- `call-tool`: Executes a tool on a specific server
- `find-tools`: Grep-like search for tools matching regex patterns
2. **src/server-manager.ts** - `McpServerManager` class that:
- Loads server configurations from JSON file
- Manages connections to multiple MCP servers
- Proxies tool calls to appropriate servers
- Handles server lifecycle and error recovery
- Implements `findTools` method for regex-based tool search
3. **src/types.ts** - Type definitions and Zod schemas for:
- Server configuration validation
- MCP SDK type exports
- Configuration file structure
- Parameter schemas for all tools
### Configuration
The server configuration is loaded from (in order of precedence):
1. Environment variable: `MCP_CONFIG_PATH`
2. Command-line argument: `--config-path`
3. Default location: `./mcp-config.json` or `{cwd}/mcp-config.json`
Configuration format (Claude Desktop compatible):
```json
{
"mcpServers": {
"server-name": {
"command": "command-to-run",
"args": ["arg1", "arg2"],
"env": { "KEY": "value" }
}
}
}
```
### Tool Naming Convention
Tools from connected servers are prefixed with the server name:
- Original tool: `list-files`
- Through hub: `server-name__list-files`
## Important Considerations
1. **Error Handling**: The hub gracefully handles server connection failures and continues operating with available servers.
2. **Environment Variables**: Server configurations can include environment variables that are passed to child processes.
3. **Logging**: Uses console.error for error messages since stdout is reserved for MCP protocol communication.
4. **No Tests**: Currently no test framework is set up. When implementing tests, consider:
- Unit tests for server-manager.ts logic
- Integration tests for MCP protocol handling
- Mock MCP server responses for testing
5. **TypeScript Configuration**:
- Target: ES2020
- Module: NodeNext with NodeNext resolution
- Strict mode enabled
- Outputs to `dist/` directory
- Declaration files generated
6. **Dependencies**:
- Keep dependencies minimal (currently only @modelcontextprotocol/sdk and zod)
- All types are exported from types.ts for consistency
7. **Binary Execution**: Configured as npm binary `mcp-hub-mcp` with shebang in index.ts