agent CLAUDE.md

CLAUDE.md

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

Repository Information

• Repository URL: https://github.com/1mcp-app/agent
• Documentation: https://docs.1mcp.app

Development Commands

# Setup
pnpm install
cp .env.example .env  # Required for development

# Build & Run
pnpm build            # Build the project
pnpm dev              # Development with auto-rebuild
pnpm watch            # Watch mode for development

# Quality Checks (run before committing)
pnpm lint && pnpm typecheck && pnpm build && pnpm test:unit

# Testing
pnpm test:unit                              # Run all unit tests
pnpm test:unit src/config/mcpConfigManager.test.ts  # Run single test file
pnpm test:unit -t "ServerManager"           # Run tests matching name pattern (-t = --testNamePattern)
pnpm test:unit:watch                        # Watch mode
pnpm test:unit:coverage                     # With coverage
pnpm test:e2e                               # E2E tests (sequential, with fixtures)
pnpm test:e2e:watch                         # E2E watch mode

# Debug
pnpm inspector                              # MCP Inspector

# Documentation
pnpm docs:dev         # Start VitePress dev server
pnpm docs:build       # Build documentation (run after doc changes)

# Binary
pnpm sea:build        # Create SEA bundle
pnpm sea:binary       # Build binary for current platform

Architecture Overview

1MCP is a unified MCP server that aggregates multiple MCP servers into one endpoint. It acts as a proxy, managing servers as subprocesses and forwarding requests from AI assistants.

Layered Architecture

src/
├── commands/           # CLI commands (yargs-based)
├── transport/          # HTTP/SSE and STDIO protocol implementations
│   └── http/
│       ├── routes/     # Endpoint handlers (oauth, sse, streamable)
│       └── middlewares/# Security, auth, tag extraction
├── core/               # Business logic
│   ├── server/         # ServerManager - lifecycle management
│   ├── capabilities/   # Tool/resource aggregation
│   ├── loading/        # mcpLoadingManager, parallelExecutor, state tracking
│   └── filtering/      # Request filtering
├── config/             # McpConfigManager with hot-reload
├── auth/               # OAuth 2.1 with scope-based authorization
├── domains/            # Self-contained business domains
│   ├── preset/             # Preset management
│   ├── backup/             # Backup management
│   ├── discovery/          # App discovery
│   ├── installation/       # App installation
│   ├── registry/           # Server registry
│   ├── server-management/  # Server management
│   └── config-change/      # Config mutation/reload observation
├── application/        # Cross-cutting services (health, config reload)
└── logger/             # Winston-based conditional logging