persistent-terminal-mcp: Instructions file for Claude Code

CLAUDE.md

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

项目概述

这是一个基于 TypeScript 的 Model Context Protocol (MCP) 服务器，提供持久化终端会话管理功能。项目实现了完整的 MCP 协议标准，支持多种客户端（Claude Desktop、Claude Code、Cursor、Cline 等）。

核心架构

主要组件

1. MCP 服务器 (src/mcp-server.ts)

   • 实现 Model Context Protocol 标准
   • 处理 JSON-RPC 通信
   • 提供工具、资源、提示词和日志功能

2. 终端管理器 (src/terminal-manager.ts)

   • 基于 node-pty 的持久化终端会话管理
   • 支持多终端会话并发
   • 智能输出处理和 Spinner 压缩
   • 自动超时清理机制

3. Web UI 系统

   • 基于 Express + WebSocket 的实时界面 (src/web-ui-server.ts)
   • 使用 xterm.js 渲染终端界面 (public/terminal.html)
   • 支持交互式操作和实时通信

4. REST API 服务器 (src/rest-server.ts, src/rest-api.ts)

   • 独立的 HTTP 服务器（端口 3001）
   • 完整的 RESTful API 接口
   • 支持非 MCP 客户端集成

数据流架构

MCP Client ↔ MCP Server ↔ Terminal Manager ↔ Node PTY ↔ Terminal Process
              ↓
        Web UI Server ↔ WebSocket ↔ Browser
              ↓
        REST API Server ↔ HTTP Client

开发命令

构建和运行

# 构建 TypeScript 项目
npm run build

# 开发模式运行 MCP 服务器
npm run dev

# 生产模式运行
npm run start

# 开发模式运行 REST API 服务器
npm run dev:rest

测试

# 运行所有测试
npm test

# 仅运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行特定集成测试
npm run test:integration:stdio
npm run test:integration:cursor
npm run test:integration:terminal

# 运行测试并生成覆盖率报告
npm test -- --coverage

示例和调试

# 基本使用示例
npm run example:basic

# REST API 演示
npm run example:rest

# 交互式演示
npm run example:interactive

# 智能读取演示
npm run example:smart

# Spinner 压缩测试
npm run example:spinner

# Web UI 测试
npm run example:webui

# 测试所有工具
npm run test:tools

环境配置

必需环境变量

# REST API 服务器端口
REST_PORT=3001

# 终端配置
MAX_BUFFER_SIZE=10000     # 最大缓冲区行数
SESSION_TIMEOUT=86400000  # 会话超时时间（24小时）

# 终端尺寸
DEFAULT_COLS=80
DEFAULT_ROWS=24

# 日志级别
LOG_LEVEL=info

开发配置

# 启用 MCP 调试模式
MCP_DEBUG=true

# 启用应用调试模式
DEBUG=true

关键技术细节

MCP 协议实现

• 使用 @modelcontextprotocol/sdk 实现
• 支持 stdio 传输模式
• 保持 stdout 纯净，所有日志输出到 stderr
• 实现完整的工具、资源、提示词和日志功能