mcp-server-manager: Instructions file for Codex

AGENTS.md

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

Project Overview

MCP Server Manager (mcpsm) is a CLI tool for managing MCP (Model Context Protocol) servers across multiple AI clients (Codex Desktop, Cursor, Windsurf, VS Code, etc.). It provides both an interactive TUI and CLI commands for server management, testing, client syncing, and daemon control.

Client Connection Model

The system uses a gateway pattern for client connections:

• A single mcpsm server is added to each connected client's configuration
• This server uses supergateway to proxy all MCP requests to the daemon on localhost:{port}/mcp
• When the port setting is changed, all connected clients are automatically updated
• Supports real-time config loading for clients without restart (Cursor, Windsurf, VS Code)

Development Commands

# Build the TypeScript project
npm run build

# Run the CLI (after build)
npm start
node dist/cli/index.js <command>

# Development mode (with hot reload)
npm run dev              # CLI
npm run dev:tui          # TUI

# Type checking
npm run typecheck

# Linting
npm run lint             # Check for issues
npm run lint:fix         # Auto-fix issues

# Testing
npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # With coverage report

# Formatting
npm run format           # Format code
npm run format:check     # Check formatting

# Clean build
npm run clean

Architecture (TypeScript v2.0)

Directory Structure

src/
├── types/              # TypeScript type definitions
│   ├── server.types.ts
│   ├── config.types.ts
│   ├── client.types.ts
│   ├── profile.types.ts
│   ├── settings.types.ts
│   ├── tool.types.ts
│   ├── auth.types.ts
│   ├── daemon.types.ts
│   ├── import-export.types.ts
│   ├── common.types.ts
│   └── index.ts        # Re-exports all types
├── services/           # Business logic services
│   ├── config.service.ts
│   ├── settings.service.ts
│   ├── profile.service.ts
│   ├── client.service.ts
│   ├── testing.service.ts
│   └── index.ts        # Re-exports all services
├── shared/             # Shared utilities
│   ├── colors.ts       # ANSI color codes
│   ├── logger.ts       # Logging utilities
│   ├── prompts.ts      # Interactive prompts
│   └── index.ts
├── cli/                # CLI implementation (commander.js)
│   ├── index.ts        # Main CLI entry point
│   └── commands/       # Command modules
│       ├── server.cmd.ts
│       ├── client.cmd.ts
│       ├── profile.cmd.ts
│       ├── settings.cmd.ts
│       ├── tools.cmd.ts
│       └── utility.cmd.ts
├── tui/                # TUI implementation
│   └── index.ts        # Main TUI entry point
└── index.ts            # Main exports