@hienlh/ppm 0.8.87 → 0.8.88

package/docs/codebase-summary.md

@@ -1,103 +1,105 @@
 # PPM Codebase Summary
 
-Generated from codebase analysis of 135+ TypeScript files, ~22.5K LOC (including multi-account feature).
+**Last Updated:** 2026-03-26
+**Version:** 0.8.60
+**Repository:** PPM (Project & Process Manager) — Multi-provider web IDE/project manager with Claude Agent SDK
+
+**Core Statistics:**
+- **303 files** across CLI, server, web, and test layers
+- **490,667 tokens** total codebase size
+- **492 passing tests** (13 new tests for provider models API)
+- **Tech Stack:** Bun (runtime), Hono (HTTP), React (UI), Claude Agent SDK (AI)
+
+---
 
 ## Directory Structure
 
 ```
-ppm/
-├── src/
-│   ├── index.ts                     # CLI entry point (Commander.js program)
-│   ├── cli/
-│   │   ├── commands/                # CLI command implementations (14 files, 1700 LOC)
-│   │   │   ├── start.ts             # Start server (background by default, --foreground/-f, --share/-s for tunnel)
-│   │   │   ├── stop.ts              # Stop daemon (reads status.json or ppm.pid, graceful shutdown)
-│   │   │   ├── restart.ts           # Restart daemon (keeps tunnel alive)
-│   │   │   ├── status.ts            # Show daemon status
-│   │   │   ├── open.ts              # Open browser to http://localhost:PORT
-│   │   │   ├── logs.ts              # Tail daemon logs
-│   │   │   ├── report.ts            # File bug report on GitHub
-│   │   │   ├── init.ts              # Initialize config (scan git repos, DB profile support)
-│   │   │   ├── projects.ts          # Add/remove/list/scan projects
-│   │   │   ├── config-cmd.ts        # View/set config values
-│   │   │   ├── git-cmd.ts           # Git operations (status, diff, log, commit)
-│   │   │   ├── chat-cmd.ts          # Chat CLI (send messages, manage sessions)
-│   │   │   └── db-cmd.ts            # Database CLI (list, query, manage connections)
-│   │   └── utils/
-│   │       └── project-resolver.ts  # Resolve project name -> path
-│   ├── server/
-│   │   ├── index.ts                 # Hono server setup, Bun.serve, WebSocket upgrade
-│   │   ├── middleware/
-│   │   │   └── auth.ts              # Token validation middleware
-│   │   ├── routes/
-│   │   │   ├── settings.ts          # GET/PUT /api/settings/ai (AI provider config)
-│   │   │   ├── projects.ts          # GET/POST /api/projects, DELETE /:name
-│   │   │   ├── accounts.ts          # GET/POST/PUT/DELETE /api/accounts, POST activate
-│   │   │   ├── project-scoped.ts    # Mount chat, git, files under /api/project/:name/*
-│   │   │   ├── chat.ts              # GET/POST/DELETE sessions, GET messages, usage, slash-items
-│   │   │   ├── git.ts               # GET status, diff, log, graph; POST commit, stage, discard
-│   │   │   ├── files.ts             # GET tree, read, diff; PUT write; POST mkdir, delete
-│   │   │   ├── database.ts          # GET/POST/PUT/DELETE /api/db/connections (CRUD), query execution
-│   │   │   └── static.ts            # Serve dist/web/index.html (frontend)
-│   │   ├── helpers/
-│   │   │   └── resolve-project.ts   # Helper to resolve project from request params
-│   │   └── ws/
-│   │       ├── chat.ts              # WebSocket chat streaming (220 LOC)
-│   │       └── terminal.ts          # WebSocket terminal I/O (terminal.service.ts integration)
-│   ├── providers/                   # AI Provider adapters (4 files, 1190 LOC)
-│   │   ├── provider.interface.ts    # AIProvider interface (createSession, sendMessage, onToolApproval)
-│   │   ├── claude-agent-sdk.ts      # Primary: SDK integration, tool approval, Windows CLI fallback, .env poisoning mitigation
-│   │   ├── mock-provider.ts         # Test provider (ignores config)
-│   │   └── registry.ts              # ProviderRegistry (singleton, router to active provider)
-│   ├── services/                    # Business logic (20 files, 3300+ LOC)
-│   │   ├── chat.service.ts          # Session lifecycle, message streaming
-│   │   ├── config.service.ts        # Config loading (YAML→SQLite migration)
-│   │   ├── db.service.ts            # SQLite persistence (schema v5, WAL mode, 9 tables, connection/account CRUD)
-│   │   ├── account.service.ts       # Account CRUD, token encryption/decryption, active selection
-│   │   ├── account-selector.service.ts # Select active account based on config
-│   │   ├── project.service.ts       # Project CRUD, scanning, resolution
-│   │   ├── file.service.ts          # File ops with path validation
-│   │   ├── git.service.ts           # Git operations (status, diff, log, graph)
-│   │   ├── terminal.service.ts      # PTY management, Bun.spawn native shell
-│   │   ├── claude-usage.service.ts  # Token tracking, cost calculation
-│   │   ├── push-notification.service.ts # Web push subscriptions
-│   │   ├── session-log.service.ts   # Session audit logs with redaction
-│   │   ├── slash-items.service.ts   # /slash command detection & completion
-│   │   ├── git-dirs.service.ts      # Cached git directory discovery
-│   │   ├── cloudflared.service.ts   # Download cloudflared binary (platform-specific)
-│   │   ├── tunnel.service.ts        # Cloudflare Quick Tunnel lifecycle
-│   │   ├── table-cache.service.ts   # Table metadata cache & search for DB connections
-│   │   └── database/                # Database adapters & registry
-│   │       ├── adapter-registry.ts  # DatabaseAdapter registry (extensible)
-│   │       ├── sqlite-adapter.ts    # SQLite connection, query execution
-│   │       ├── postgres-adapter.ts  # PostgreSQL connection, query execution
-│   │       ├── init-adapters.ts     # Initialize adapters at server start
-│   │       └── readonly-check.ts    # isReadOnlyQuery() safety regex (CTE-safe)
-│   ├── lib/                         # Shared utilities (2 files)
-│   │   ├── account-crypto.ts        # AES-256 encryption/decryption for API keys
-│   │   └── network-utils.ts         # Network utility helpers
-│   ├── types/                       # TypeScript interfaces (7 files, 450 LOC)
-│   │   ├── api.ts                   # ApiResponse envelope, WebSocket message types
-│   │   ├── chat.ts                  # Session, Message, ChatEvent types
-│   │   ├── config.ts                # Config schema
-│   │   ├── database.ts              # DatabaseAdapter, DbConnectionConfig, DbTableInfo, etc.
-│   │   ├── git.ts                   # GitStatus, GitDiff, GitCommit types
-│   │   ├── project.ts               # Project interface
-│   │   └── terminal.ts              # Terminal types
-│   └── web/                         # React frontend (Vite)
-│       ├── main.tsx                 # React mount (<App> into #root)
-│       ├── app.tsx                  # Root component (auth check, project load, theme)
-│       ├── stores/                  # Zustand state stores (6 files)
-│       │   ├── project-store.ts     # Active project, projects list, localStorage persistence
-│       │   ├── tab-store.ts         # Tab facade, delegates to panel-store
-│       │   ├── panel-store.ts       # Grid layout, panel creation/movement, keep-alive snapshots
-│       │   ├── panel-utils.ts       # Layout algorithm helpers, grid manipulation
-│       │   ├── file-store.ts        # File cache
-│       │   └── settings-store.ts    # Theme, sidebar state, git view mode, device name
-│       ├── hooks/                   # Custom React hooks (9 files)
-│       │   ├── use-chat.ts          # Chat streaming, messages, approvals, context window tracking
-│       │   ├── use-websocket.ts     # WebSocket connection with auto-reconnect
-│       │   ├── use-terminal.ts      # Terminal connection and streaming
+src/
+├── cli/
+│   ├── commands/                # 13 CLI commands (start, stop, init, config, chat, db, git, etc.)
+│   └── utils/
+│       └── project-resolver.ts  # Resolve project name -> path
+├── server/
+│   ├── index.ts                 # Hono server setup, Bun.serve, WebSocket upgrade
+│   ├── middleware/
+│   │   └── auth.ts              # Token validation middleware
+│   ├── routes/
+│   │   ├── settings.ts          # GET/PUT /api/settings/ai, GET /api/settings/ai/providers/:id/models
+│   │   ├── chat.ts              # Sessions, messages, GET /chat/providers/:providerId/models
+│   │   ├── projects.ts          # Project CRUD, reorder, color
+│   │   ├── accounts.ts          # Account management (multi-account support)
+│   │   ├── database.ts          # DB connection CRUD, schema management
+│   │   ├── git.ts               # Git operations (status, commit, log, graph)
+│   │   ├── files.ts             # File operations (read, write, tree)
+│   │   ├── mcp.ts               # MCP server CRUD + import (GET, POST, PUT, DELETE)
+│   │   ├── upgrade.ts           # Version checking, upgrade
+│   │   └── static.ts            # Serve frontend (dist/web)
+│   ├── helpers/
+│   │   └── resolve-project.ts   # Resolve project from request params
+│   └── ws/
+│       ├── chat.ts              # WebSocket chat streaming
+│       └── terminal.ts          # WebSocket terminal I/O
+├── providers/                   # AI Provider adapters
+│   ├── provider.interface.ts    # AIProvider interface (ADDED: listModels?())
+│   ├── claude-agent-sdk.ts      # Primary provider (listModels: hardcoded 2 models)
+│   ├── cursor-cli/
+│   │   └── cursor-provider.ts   # CLI-based provider (listModels: subprocess with TTL cache)
+│   ├── cli-provider-base.ts     # Abstract base for CLI providers
+│   ├── mock-provider.ts         # Test provider
+│   └── registry.ts              # Provider routing (list() vs listAll())
+├── services/                    # Business logic (25+ files)
+│   ├── chat.service.ts          # Session/message streaming
+│   ├── config.service.ts        # Config loading/persistence
+│   ├── db.service.ts            # SQLite CRUD (schema migrations)
+│   ├── file.service.ts          # File operations
+│   ├── git.service.ts           # Git commands
+│   ├── terminal.service.ts      # PTY management
+│   ├── account.service.ts       # Account CRUD & encryption
+│   ├── upgrade.service.ts       # Version checking, installation
+│   ├── mcp-config.service.ts    # MCP server CRUD (list, get, set, remove, import)
+│   ├── database/
+│   │   ├── adapter-registry.ts  # SQLite/Postgres adapter registry
+│   │   ├── sqlite-adapter.ts
+│   │   ├── postgres-adapter.ts
+│   │   └── readonly-check.ts    # CTE-safe readonly validation
+│   └── ... (20+ other services)
+├── lib/
+│   ├── account-crypto.ts        # AES-256 encryption
+│   └── network-utils.ts
+├── types/
+│   ├── chat.ts                  # Session, Message, ChatEvent, ModelOption, AIProvider
+│   ├── api.ts                   # ApiResponse envelope
+│   ├── config.ts
+│   ├── database.ts
+│   ├── git.ts
+│   ├── mcp.ts                   # McpServerConfig, McpTransportType, validation
+│   ├── project.ts
+│   └── terminal.ts
+└── web/                         # React frontend (Vite + React 18)
+    ├── app.tsx                  # Root component
+    ├── stores/                  # Zustand state (6 stores)
+    ├── hooks/                   # Custom hooks (9 hooks)
+    ├── components/
+    │   ├── chat/
+    │   │   ├── chat-tab.tsx
+    │   │   ├── message-list.tsx
+    │   │   ├── message-input.tsx
+    │   │   ├── provider-selector.tsx
+    │   │   ├── chat-history-bar.tsx # ADDED: Provider badges, provider-aware usage
+    │   │   └── ... (6 other chat components)
+    │   ├── settings/
+    │   │   ├── ai-settings-section.tsx # UPDATED: Per-provider tabs, dynamic model dropdowns
+    │   │   ├── mcp-settings-section.tsx # ADDED: MCP servers tab (list, add, edit, delete)
+    │   │   └── mcp-server-dialog.tsx    # ADDED: Add/Edit MCP server dialog
+    │   ├── database/
+    │   ├── editor/
+    │   ├── explorer/
+    │   ├── git/
+    │   ├── layout/
+    │   ├── terminal/
+    │   └── ui/
+    └── lib/
 │       │   ├── use-url-sync.ts      # Sync browser URL with active project/tab state
 │       │   ├── use-tab-drag.ts      # Tab drag-and-drop logic
 │       │   ├── use-global-keybindings.ts # Global shortcuts (Shift+Shift palette, Alt+[/] tab cycling)
@@ -107,6 +109,7 @@ ppm/
 │       ├── lib/                     # Utilities (12 files)
 │       │   ├── api-client.ts        # Fetch wrapper with auth token, envelope unwrapping
 │       │   ├── api-settings.ts      # AI settings API client (GET/PUT /api/settings/ai)
+│       │   ├── api-mcp.ts           # ADDED: MCP settings API client (CRUD + import)
 │       │   ├── ws-client.ts         # WebSocket with exponential backoff + Cloudflare handshake
 │       │   ├── file-support.ts      # File type detection (language, icons, preview)
 │       │   ├── project-avatar.ts    # Smart project initials (collision resolution)
@@ -370,11 +373,174 @@ UI updates staged/unstaged lists
 - PWA manifest, service worker
 - Assets (~500KB gzipped)
 
+## Multi-Provider Architecture (v0.8.60)
+
+### Dynamic Model Listing Feature
+
+**Problem:** Different AI providers expose different models. Claude has hardcoded models, but CLI-based providers (e.g., Cursor) discover models at runtime.
+
+**Solution:** Optional `listModels()` method on `AIProvider` interface
+
+### Provider Interface
+
+```typescript
+// src/types/chat.ts
+export interface ModelOption {
+  value: string;    // Model ID (e.g., "claude-sonnet-4-6")
+  label: string;    // Display name (e.g., "Claude Sonnet 4.6")
+}
+
+interface AIProvider {
+  // Required methods
+  createSession(): Promise<Session>;
+  sendMessage(sessionId, message, context?): AsyncIterable<ChatEvent>;
+
+  // Optional methods
+  listModels?(): Promise<ModelOption[]>;
+  isAvailable?(): Promise<boolean>;
+  // ... (5 other optional methods)
+}
+```
+
+### Provider Implementations
+
+#### Claude (agent-sdk.ts)
+- `listModels()` returns hardcoded 2 models: Sonnet 4.6, Opus 4.6
+- Direct implementation (no subprocess)
+
+#### Cursor (cursor-provider.ts)
+- `listModels()` runs `cursor-agent --list-models` subprocess
+- 5-minute TTL cache (prevents repeated subprocess calls)
+- 10-second timeout (graceful fallback to empty list)
+- Extends `CliProvider` abstract base
+
+#### Mock (mock-provider.ts)
+- For testing; returns canned models
+
+### API Endpoints
+
+**Global Models Endpoint** (`GET /api/settings/ai/providers/:id/models`)
+```typescript
+// Used in Settings UI (no project context needed)
+settingsRoutes.get("/ai/providers/:id/models", async (c) => {
+  const provider = providerRegistry.get(c.req.param("id"));
+  const models = await provider.listModels?.() ?? [];
+  return c.json(ok(models));
+});
+```
+
+**Project-Scoped Models Endpoint** (`GET /api/project/:name/chat/providers/:providerId/models`)
+```typescript
+// Used in Chat tab (scoped to project for consistency)
+chatRoutes.get("/providers/:providerId/models", async (c) => {
+  const provider = providerRegistry.get(c.req.param("providerId"));
+  const models = await provider.listModels?.() ?? [];
+  return c.json(ok(models));
+});
+```
+
+### Provider Registry Pattern
+
+**list() — User-facing providers:**
+```typescript
+list(): ProviderInfo[] {
+  return [
+    { id: "claude", name: "Claude" },
+    { id: "cursor", name: "Cursor" }
+    // mock excluded
+  ];
+}
+```
+
+**listAll() — All providers (internal):**
+```typescript
+listAll(): ProviderInfo[] {
+  return [..., { id: "mock", name: "Mock" }];
+}
+```
+
+**Auto-Bootstrap:**
+```typescript
+// On startup, detect CLI providers
+async bootstrapProviders() {
+  const cursor = this.providers.get("cursor");
+  if (cursor && await cursor.isAvailable?.()) {
+    // Auto-create config entry if detected
+    // Save config (only if new)
+  }
+}
+```
+
+### UI Components
+
+#### AI Settings Section (ai-settings-section.tsx) — UPDATED
+- Per-provider tabs (Claude, Cursor, etc.)
+- Dynamic model dropdowns fetched from `/api/settings/ai/providers/:id/models`
+- Fallback to hardcoded models if API call fails
+- Provider-aware settings (SDK vs CLI options)
+
+#### Chat History Bar (chat-history-bar.tsx) — ADDED
+- Provider badges showing active provider for each session
+- Provider-aware usage display:
+  - **Claude:** Full stats `(tokens_in:X, tokens_out:Y, cost: $Z)`
+  - **Other:** Context-only `(tokens: X)`
+
+### Configuration
+
+```yaml
+ai:
+  default_provider: claude
+  providers:
+    claude:
+      type: agent-sdk
+      model: claude-sonnet-4-6  # from listModels()
+      effort: high
+      max_turns: 100
+    cursor:
+      type: cli
+      model: cursor-fast        # from listModels()
+```
+
+### Testing
+
+**New Integration Tests (13 tests):**
+- `provider-models-api.test.ts` — Model API endpoints
+- `chat-service-multi-provider.test.ts` — Multi-provider flows
+- `cursor-provider.test.ts` — Subprocess TTL cache, timeout handling
+
+---
+
 ## Testing Strategy
 
 | Test Type | Location | Coverage |
 |-----------|----------|----------|
 | Unit | tests/unit/ | Services, utilities |
-| Integration | tests/integration/ | API routes, WebSocket |
+| Integration | tests/integration/ | API routes, WebSocket, provider models |
 | E2E | None yet | Planned for v3 |
 
+**Key Gotchas:**
+- Test DB isolated per test (never writes to ~/.ppm/ppm.db)
+- Auth disabled in test mode (test-setup.ts)
+- Mock provider used for deterministic responses
+- 492 passing tests (0 failures, v0.8.60)
+
+---
+
+## Recent Changes (v0.8.60)
+
+### Added
+- **Dynamic Model Listing** — `listModels?()` on AIProvider interface
+- **Provider Models APIs** — Global and project-scoped endpoints
+- **AI Settings UI** — Per-provider tabs with dynamic model dropdowns
+- **Chat History Badges** — Provider-aware usage display
+- **13 new integration tests** for provider models API
+
+### Technical Details
+- `ModelOption` type: `{ value: string; label: string }`
+- Claude: Hardcoded 2 models
+- Cursor: Subprocess with 5-min TTL cache, 10s timeout
+- Registry: `list()` vs `listAll()` distinction
+- Bootstrap: Auto-detect CLI providers on startup
+
+---
+

package/docs/project-changelog.md

@@ -2,11 +2,11 @@
 
 All notable changes to PPM are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
 
-**Current Version:** v0.8.76
+**Current Version:** v0.8.87
 
 ---
 
-## [0.8.77] — 2026-04-01 (Planned)
+## [0.8.77] — 2026-04-01
 
 ### Added
 - **Deterministic Tab URLs + Backend Workspace Sync**
@@ -41,6 +41,41 @@ All notable changes to PPM are documented here. Format follows [Keep a Changelog
 
 ---
 
+## [0.8.63] — 2026-03-28
+
+### Added
+- **MCP Server Management** — Configure Model Context Protocol servers via Settings UI
+  - REST API: GET/POST/PUT/DELETE `/api/settings/mcp`, plus import endpoints
+  - Storage: SQLite `mcp_servers` table (name, transport, config JSON)
+  - UI: Settings tab with server list, add/edit dialog, delete action
+  - Auto-import: Reads `~/.claude.json` on first access (skips existing/invalid)
+  - Validation: Name (alphanumeric, max 50 chars) + transport-specific config checks
+  - SDK integration: Servers passed to `query()` as `mcpServers`, tools auto-allowed via `mcp__*` wildcard
+
+### Technical Details
+- **Files Created:**
+  - `src/types/mcp.ts` — McpServerConfig types, validation functions
+  - `src/services/mcp-config.service.ts` — CRUD service + bulk import
+  - `src/server/routes/mcp.ts` — REST API endpoints
+  - `src/web/lib/api-mcp.ts` — Frontend API client
+  - `src/web/components/settings/mcp-settings-section.tsx` — Settings UI
+  - `src/web/components/settings/mcp-server-dialog.tsx` — Add/Edit dialog
+- **Files Modified:**
+  - `src/services/db.service.ts` — Schema v8 migration (mcp_servers table)
+  - `src/server/index.ts` — Route registration
+  - `src/providers/claude-agent-sdk.ts` — mcpServers + mcp__* allowedTools
+  - `src/web/components/settings/settings-tab.tsx` — MCP category added
+
+---
+
+## [0.8.62] — 2026-03-26
+
+### Added
+- **Cmd+Shift+V shortcut** — Command palette entry for voice input
+- **Voice input** — Web Speech API integration for chat
+
+---
+
 ## [0.8.61] — 2026-03-26 (Beta)
 
 ### Added
@@ -76,7 +111,7 @@ All notable changes to PPM are documented here. Format follows [Keep a Changelog
   - `src/services/chat.service.ts` — Use optional methods instead of duck-typing
   - `src/web/components/chat/session-picker.tsx` — Integrated provider selector
 - **Breaking Changes:** None (backward compatible, all tests passing)
-- **Architecture:** All phases complete (6/6), 479 tests passing
+- **Architecture:** All phases complete (6/6), 555 tests passing
 
 ### Benefits
 - Extensible foundation for Codex, Gemini, and future providers (~100-150 lines each)

package/docs/project-roadmap.md

@@ -58,13 +58,13 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 
 **Theme:** Multi-provider AI (Claude + Cursor) + extension system. Ship a focused release, expand providers later.
 
-**Overall progress: ~40%** (1/3 features complete, merge all at 100%)
+**Overall progress: ~53%** (2/3 features complete, merge all at 100%)
 
 | Feature | Priority | Status | Description |
 |---------|----------|--------|-------------|
 | **Multi-provider AI** | Critical | ✅ Done | ProviderInterface, registry, Cursor CLI, CLI provider base, UI provider/model selector, permission mode selector, system prompt customization, comprehensive tests — all on beta branch. |
+| **MCP Management** | Medium | ✅ Done | REST API (CRUD + import), SQLite storage, Settings UI, auto-import from `~/.claude.json`, validation, SDK integration. |
 | **Extension architecture** | High | 🔴 0% | Dynamic extension loading. Extensions = npm packages. First extension: extract DB viewer from core. Extension API: register routes, UI panels, sidebar tabs, skills. Config: `"extensions": ["@ppm/ext-database", "@ppm/ext-docker"]`. |
-| **MCP Management** | Medium | 🔴 0% | UI to add/remove/configure MCP servers. Test connection. Per-project MCP overrides. Store in SQLite. Pass to Agent SDK via `mcpServers`. |
 
 **Multi-provider — v0.9 scope (reduced):**
 - Tier 1 (full agentic): Claude Agent SDK — file edit, terminal, git, full autonomy

package/docs/system-architecture.md

@@ -977,6 +977,157 @@ ppm db data <name> <table>   # Show table data (paginated)
 
 ---
 
+## MCP Server Management
+
+### Overview
+MCP (Model Context Protocol) servers extend Claude with custom tools and resources. PPM manages MCP server configurations via Settings UI, storing them in SQLite and passing them to the Claude Agent SDK.
+
+**Features:**
+- **Add/Edit/Delete** MCP servers via Settings UI
+- **Auto-import** from `~/.claude.json` on first access (convenience, no forced import)
+- **Three transport types:** stdio, HTTP, SSE
+- **Validation** on name and config before storage
+- **SDK integration:** Servers passed to `query()` as `mcpServers` object, tools auto-allowed via `mcp__*` wildcard
+
+### Storage Schema
+
+```sql
+CREATE TABLE mcp_servers (
+  name TEXT PRIMARY KEY,
+  transport TEXT NOT NULL DEFAULT 'stdio',  -- 'stdio' | 'http' | 'sse'
+  config TEXT NOT NULL,                     -- JSON: McpServerConfig
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+```
+
+**Config Format (JSON):**
+```json
+{
+  "type": "stdio",
+  "command": "path/to/server",
+  "args": ["--flag"],
+  "env": { "VAR": "value" }
+}
+```
+
+Or HTTP/SSE:
+```json
+{
+  "type": "http",
+  "url": "http://localhost:3000",
+  "headers": { "Authorization": "Bearer token" }
+}
+```
+
+### REST API
+
+**Endpoints** (`src/server/routes/mcp.ts`):
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| **GET** | `/api/settings/mcp` | List all servers; auto-import on first access |
+| **GET** | `/api/settings/mcp/:name` | Get single server config |
+| **POST** | `/api/settings/mcp` | Add new server (validates name + config) |
+| **PUT** | `/api/settings/mcp/:name` | Update existing server |
+| **DELETE** | `/api/settings/mcp/:name` | Remove server |
+| **GET** | `/api/settings/mcp/import/preview` | Preview servers in `~/.claude.json` |
+| **POST** | `/api/settings/mcp/import` | Bulk import from `~/.claude.json` |
+
+**Add Server Example:**
+```bash
+POST /api/settings/mcp
+Content-Type: application/json
+
+{
+  "name": "file-server",
+  "config": {
+    "type": "stdio",
+    "command": "/usr/local/bin/file-server",
+    "args": ["--port", "8000"]
+  }
+}
+```
+
+### Service Layer
+
+**McpConfigService** (`src/services/mcp-config.service.ts`):
+- `list()` — Record<name, McpServerConfig> (SDK-compatible format)
+- `listWithMeta()` — Array with metadata (for UI)
+- `get(name)` — Single server config
+- `set(name, config)` — Add or update (upsert)
+- `remove(name)` — Delete server
+- `exists(name)` — Check if name exists
+- `bulkImport(servers)` — Transactional import from `~/.claude.json`, skips existing/invalid
+
+**Validation:**
+- `validateMcpName(name)` — alphanumeric + hyphens/underscores, max 50 chars
+- `validateMcpConfig(config)` — type-specific checks (command for stdio, url for http/sse)
+
+### Frontend Integration
+
+**UI Components:**
+- `MCP Settings Section` (`src/web/components/settings/mcp-settings-section.tsx`) — Tab in Settings UI
+- `MCP Server Dialog` (`src/web/components/settings/mcp-server-dialog.tsx`) — Add/Edit modal
+- `API client` (`src/web/lib/api-mcp.ts`) — Fetch/mutate operations
+
+**Workflow:**
+1. User opens Settings → MCP tab
+2. **GET** `/api/settings/mcp` (auto-imports on first access)
+3. Display list with transport badge + actions (edit, delete)
+4. Click "Add" → Dialog with name + transport selector + config fields
+5. **POST** to `/api/settings/mcp` or **PUT** to update
+6. On success, list refreshes
+
+### SDK Integration
+
+**Claude Agent SDK Provider** (`src/providers/claude-agent-sdk.ts`):
+```typescript
+// Line ~574
+const mcpServers = mcpConfigService.list();
+const hasMcp = Object.keys(mcpServers).length > 0;
+
+// Line ~589: Pass to query() if servers exist
+const mcpTools = ["mcp__*"];
+const queryConfig = {
+  // ... other options
+  ...(hasMcp && { mcpServers }),
+  allowedTools: [...otherTools, ...mcpTools],
+};
+
+const query = new Query(messages, queryConfig);
+```
+
+**Tool Allow List:**
+- All MCP tools automatically allowed via wildcard `mcp__*`
+- MCP server connection failures don't block chat (logged as warning)
+
+### Import Flow
+
+**Auto-import on first access:**
+1. GET `/api/settings/mcp` called
+2. If table is empty, read `~/.claude.json`
+3. If `mcpServers` key exists, bulk import (validate + skip duplicates)
+4. Return populated list
+
+**Manual import:**
+1. GET `/api/settings/mcp/import/preview` — show what's available
+2. POST `/api/settings/mcp/import` — import validated servers
+3. Returns `{ imported: N, skipped: M }`
+
+### Error Handling
+
+| Scenario | Response |
+|----------|----------|
+| Invalid name (non-alphanumeric) | 400 Bad Request |
+| Invalid config (missing required fields) | 400 Bad Request |
+| Duplicate name | 409 Conflict |
+| Server not found (GET/:name, PUT/:name, DELETE/:name) | 404 Not Found |
+| `~/.claude.json` not found (import) | 404 Not Found |
+| Corrupt config JSON (recovery) | Log warning, skip entry, continue |
+
+---
+
 ## Deployment Architecture
 
 ### Single-Machine Deployment (Current)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.87",
+  "version": "0.8.88",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",