LogicStamp/logicstamp-mcp

 *示例工作流：`stamp context --strict-watch` 生成上下文包，MCP 驱动的助手使用这些包来解释组件架构（此处展示 ThemeContext）。*

📑 目录

- [概述](#overview) - [功能](#-features) - [前提条件](#prerequisites) - [快速开始](#quick-start) - [使用示例](#usage-example) - [工具参考](#tool-reference) - [启动流程](#startup-ritual) - [文档](#documentation) - [故障排除](#troubleshooting) - [开发](#development) - [架构](#architecture) - [要求](#requirements) - [需要帮助？](#need-help) - [许可证](#license)

## 概述 此 MCP 服务器通过 LogicStamp Context 的分析引擎，为 AI 助手提供对代码库的结构化访问。它充当 `stamp` CLI 的轻量包装层，提供： - **基于快照的分析** — 在修改前捕获代码库状态 - **组件契约** — 提取属性、状态、钩子和依赖关系 - **样式元数据** — 提取 Tailwind 类、SCSS 模块、framer-motion 动画、颜色调色板、布局模式 - **依赖关系图** — 理解组件之间的关系 - **漂移检测** — 在修改后验证变更 - **令牌优化** — 通过可配置的代码包含模式控制上下文大小 ## ⚡ 功能 ### 7 种工具 1. **`logicstamp_refresh_snapshot`** — 分析项目并创建快照 2. **`logicstamp_list_bundles`** — 列出可用的组件包 3. **`logicstamp_read_bundle`** — 读取完整组件契约 + 依赖关系图 4. **`logicstamp_compare_snapshot`** — 检测编辑后的变更 5. **`logicstamp_compare_modes`** — 生成所有模式下的令牌成本对比 6. **`logicstamp_read_logicstamp_docs`** — 读取 LogicStamp 文档 7. **`logicstamp_watch_status`** — 检查是否处于监视模式（用于增量重建） ### 主要优势 - **上下文感知编辑** — AI 在修改前读取实际的组件契约 - **自我验证** — AI 通过漂移检测验证其自身的修改 - **令牌高效** — 仅加载与任务相关的包 - **安全默认** — 变更必须通过漂移检查才能被批准 - **监视模式感知** — 检测 `stamp context --watch` 是否正在运行，并跳过重建（上下文已保持最新） ## 前提条件 1. **Node.js** >= 20 2. **LogicStamp Context CLI** — `stamp` 命令必须安装并在 PATH 中可用 ```bash npm install -g logicstamp-context ``` ## 快速开始 **设置只需进行一次** — 配置 MCP 服务器后，它将在所有项目中可用。MCP 客户端会在需要时自动启动服务器，无需手动启动。 1. **安装前提条件**（如果尚未安装）： ```bash npm install -g logicstamp-context # 必需：LogicStamp CLI npm install -g logicstamp-mcp # MCP 服务器 ``` 2. **配置你的 MCP 客户端**（一次性设置） — 为你的平台创建配置文件： - **Cursor**：创建 `~/.cursor/mcp.json`（macOS/Linux）或 `%USERPROFILE%\.cursor\mcp.json`（Windows） - **Claude CLI**：创建 `~/.claude.json`（macOS/Linux）或 `%USERPROFILE%\.claude.json`（Windows） - **Claude Desktop**：创建 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows） 添加以下配置： ```json { "mcpServers": { "logicstamp": { "command": "npx", "args": ["-y", "logicstamp-mcp"] } } } ``` **注意**：`-y` 告诉 `npx` 不要提示（由于 MCP 客户端通常在无终端环境下运行，提示可能导致挂起）。某些客户端可能需要 `"type": "stdio"` — 如果上述配置不生效，请添加该字段。详见[集成指南](docs/integrations/)获取平台特定细节： - [Claude CLI 集成](docs/integrations/claude-cli.md) — 适用于 Claude Code 用户 - [Claude Desktop 集成](docs/integrations/claude-desktop.md) — 适用于 Claude Desktop 用户 - [Cursor 集成](docs/integrations/cursor.md) — 适用于 Cursor IDE 用户 3. **重启 MCP 客户端**（Cursor/Claude Desktop）或使用 `claude mcp list`（Claude CLI）验证 4. **开始使用 LogicStamp：** ```bash cd /path/to/your/react-project claude # 或打开 Cursor 询问你的 AI 助手：“可以分析我的 React 项目吗？” ``` 详细设置说明请参考[快速开始指南](docs/quickstart.md)。 ## 使用示例 ``` You: "Analyze the Button component in my project" AI: 1. Uses logicstamp_refresh_snapshot to create snapshot 2. Uses logicstamp_list_bundles to find Button component 3. Uses logicstamp_read_bundle to read Button's contract 4. Provides detailed analysis of Button's props, state, hooks, etc. ``` 更多示例和工作流程请参见[MCP 集成指南](docs/mcp_integration.md#llm-workflow) 中的[使用示例](docs/mcp_integration.md#llm-workflow)。 ## 工具参考 MCP 服务器提供 7 种工具。完整的 API 文档（含输入/输出示例）请参见[MCP 集成指南](docs/mcp_integration.md#mcp-tools-mvp)。

📋 快速参考

**`logicstamp_refresh_snapshot`** — 创建当前代码库状态的快照（步骤 1） - 参数：`profile`（可选）、`mode`（可选）、`includeStyle`（可选）、`depth`（可选）、`projectPath`（必需）、`cleanCache`（可选）、`skipIfWatchActive`（可选） - 返回：`snapshotId`、`summary`、`folders`、`watchMode`（如果激活） - **调用其他工具前必须先调用此方法** - **注意**：`projectPath` 是必需的 — 必须是项目根目录的绝对路径。省略此参数可能导致服务器挂起。 - **监视模式优化**：设置 `skipIfWatchActive: true` 可在监视模式运行时跳过重建。当监视模式（`stamp context --watch`）激活时，上下文已通过增量重建保持最新 — 无需再次重建 - **深度参数**：默认情况下，依赖关系图包含嵌套组件（depth=2）。若只需直接依赖，请显式设置 `depth: 1`。默认 depth=2 确保嵌套组件包含在依赖关系图中。 - 如果检测到损坏，会自动清理缓存 **`logicstamp_list_bundles`** — 列出用于选择性加载的可用包（步骤 2） - 参数：`snapshotId`（必需）、`folderPrefix`（可选） - 返回：包含元数据的 `bundles` 数组 - **在 refresh_snapshot 后调用此方法** 以发现可用包 **`logicstamp_read_bundle** — 读取完整组件契约和依赖关系图（步骤 3） - 参数：`snapshotId`（必需）、`bundlePath`（必需）、`rootComponent`（可选） - 返回：包含契约和依赖关系图的完整包 - **这是包含有价值数据的位置** — 优先使用包而非原始源文件 **`logicstamp_compare_snapshot`** — 检测编辑后的变更 - 参数： - `profile`（可选）：分析配置文件（默认：`llm-chat`） - `mode`（可选）：代码包含模式（默认：`header`） - `includeStyle`（可选）：在 comparison 中包含样式元数据。仅在 `forceRegenerate` 为 `true` 时生效（默认：`false`） - `depth`（可选）：依赖遍历深度。仅在 `forceRegenerate` 为 `true` 时使用。**注意**：默认情况下，依赖关系图包含嵌套组件（depth=2）。若只需直接依赖，请设置 `depth: 1`。默认 depth=2 确保嵌套组件包含在依赖关系图中。 - `forceRegenerate`（可选）：强制在比较前重建上下文。`false` 时从磁盘读取现有 `context_main.json`（快速）。`true` 时运行 `stamp context` 重建（默认：`false`） - `projectPath`（可选）：项目路径（默认为当前目录） - `baseline`（可选）：比较基准：`disk`（默认）、`snapshot` 或自定义路径 - `cleanCache`（可选）：强制清理缓存（默认：`false`，自动检测损坏） - 返回：包含变更详情的比较结果 - **注意**：默认情况下（`forceRegenerate: false`），从磁盘读取以实现快速比较。设置 `forceRegenerate: true` 可确保获取新鲜上下文，或当 `context_main.json` 缺失时使用。 **`logicstamp_compare_modes`** — 生成所有模式下的令牌成本对比 - 参数：`projectPath`（可选）、`cleanCache`（可选） - 返回：各模式（none/header/header+style/full）的令牌计数、节省百分比、文件统计 - **使用此工具** 以了解令牌成本，或在用户询问令牌预算/优化时使用 **`logicstamp_read_logicstamp_docs`** — 读取 LogicStamp 文档 - 参数：无 - 返回：完整的 LogicStamp 文档包 - **当感到困惑时使用此工具** — 解释 LogicStamp、工作流程和最佳实践 **`logicstamp_watch_status`** — 检查监视模式是否激活 - 参数：`projectPath`（必需）、`includeRecentLogs`（可选）、`logLimit`（可选） - 返回：`watchModeActive`、`status`（如果激活）、`recentLogs`（如果请求）、`message` - **使用此工具** 在调用 `refresh_snapshot` 前检查 `stamp context --watch` 是否正在运行 - **当监视模式激活时**：上下文通过增量重建自动保持最新 — 可跳过重建并直接读取现有包

## 启动流程 在开始使用新项目时，请使用[启动流程](docs/startup-ritual.md)引导 AI。这确保 AI： 1. 首先调用 `logicstamp_refresh_snapshot` 2. 尽可能使用包而非原始源文件 3. 遵循推荐的 LogicStamp 工作流程 ## 文档 ### MCP 专属文档（本仓库） - **[快速开始指南](docs/quickstart.md)** — 几分钟内上手 - **[启动流程](docs/startup-ritual.md)** — 新项目启动时推荐的提示消息 - **[MCP 集成指南](docs/mcp_integration.md)** — 完整的 API 参考与架构 - **[集成指南](docs/integrations/)** — 平台特定设置（Claude CLI、Claude Desktop、Cursor） ### 规范 LogicStamp 文档（冗余来源） **完整的 CLI 与 Context 文档：** - **主要入口**：[logicstamp.dev/docs/cli/context](https://logicstamp.dev/docs/cli/context) —— 完整文档（最佳用户体验） - **备用入口**：[CLI 仓库文档](https://github.com/LogicStamp/logicstamp-context) —— GitHub 文档（始终可用且版本化） **关键主题**（主入口与备用入口均涵盖）： | 主题 | 主入口（着陆页） | 备用（GitHub） | |------|----------------|---------------| | **使用指南** | [logicstamp.dev/docs/cli/usage](https://logicstamp.dev/docs/cli/usage) | [GitHub](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/usage.md) | | **UIF 契约** | [logicstamp.dev/docs/cli/uif-contracts](https://logicstamp.dev/docs/cli/uif-contracts) | [GitHub](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/uif_contracts.md) | | **模式参考** | [logicstamp.dev/docs/cli/schema](https://logicstamp.dev/docs/cli/schema) | [GitHub](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/schema.md) | | **CLI 命令** | [logicstamp.dev/docs/cli/context](https://logicstamp.dev/docs/cli/context) | [GitHub](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/context.md) | | **比较模式** | [logicstamp.dev/docs/cli/compare-modes](https://logicstamp.dev/docs/cli/compare-modes) | [GitHub](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/compare-modes.md) | | **限制** | [logicstamp.dev/docs/complete-reference/known-limitations](https://logicstamp.dev/docs/complete-reference/known-limitations) | [GitHub](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/limitations.md) | **注意：** - 文档维护在 CLI 仓库中，并与着陆页同步 - 若着陆页不可用，请使用备用 GitHub 链接 - `logicstamp_read_logicstamp_docs` 工具返回一个嵌入式 LLM 聚焦的文档快照（`docs/logicstamp-for-llms.md`），用于离线使用 ## 故障排除 ### 常见问题 **"stamp: command not found"** - 安装 LogicStamp Context CLI：`npm install -g logicstamp-context` **服务器未显示** - 验证安装：`npm list -g logicstamp-mcp` - 手动测试服务器：`npx logicstamp-mcp`（应等待 stdin，按 Ctrl+C 退出） - 检查 MCP 客户端的配置（请参考集成指南） - 完全重启 MCP 客户端 **"Snapshot not found"** - 在使用其他工具前，始终先调用 `logicstamp_refresh_snapshot` 更多详细故障排除请参见： - [快速开始指南中的故障排除](docs/quickstart.md#troubleshooting) - 集成指南中的平台特定问题 - [MCP 集成指南](docs/mcp_integration.md) 获取架构详情 ## 开发 ### 构建 ``` npm install npm run build ``` ### 运行服务器 **重要：** 无需手动启动 MCP 服务器。配置后，MCP 客户端（Cursor、Claude Desktop 等）会在需要时自动启动服务器。以下命令仅用于测试/调试。 **仅用于测试/调试：** **从源码构建后：** ``` npm start # 或直接 node dist/index.js ``` **全局安装后：** ``` npx logicstamp-mcp ``` **注意：** 服务器通过 stdio（标准输入/输出）运行并等待 MCP 协议消息。配置 MCP 客户端（Claude CLI、Cursor 等）后，客户端会自动启动服务器 — 无需手动运行。以上命令仅用于： - 开发期间测试服务器 - 调试连接问题 - 验证服务器是否正确启动 手动运行时，服务器将等待 stdin 输入。按 `Ctrl+C` 退出。 ### 监视模式 ``` npm run dev ``` 开发详情请参见[MCP 集成指南](docs/mcp_integration.md)。 ## 架构 MCP 服务器遵循以下设计原则： 1. **轻量包装层** — 调用现有的 `stamp` CLI 2. **状态化快照** — 跟踪编辑前后的上下文 3. **只读** — 服务器从不写入项目文件 4. **令牌高效** — 选择性加载包 有关详细架构文档，请参见[MCP 集成指南](docs/mcp_integration.md#architecture)。 ## 要求 LogicStamp MCP 服务器需要： - Node.js >= 20 - TypeScript 代码库（React、Next.js、Vue（TS/TSX）、Express 或 NestJS） - **`stamp context` 命令** — 必须安装并在 PATH 中可用： - CLI 生成 `context_main.json` 文件 - MCP 服务器直接读取这些 JSON 文件（无需特殊） ## 需要帮助？ - **问题** — [github.com/LogicStamp/logicstamp-mcp/issues](https://github.com/LogicStamp/logicstamp-mcp/issues) - **路线图** — [logicstamp.dev/roadmap](https://logicstamp.dev/roadmap) ## 许可证 [MIT](LICENSE)

品牌与归属

LogicStamp 吉祥物狐狸及相关品牌资产属于 © 2025 Amit Levi。未经许可，不得用于第三方品牌。

贡献

欢迎提交问题和 PR！请参考[贡献指南](CONTRIBUTING.md)。 本项目遵循[行为准则](CODE_OF_CONDUCT.md)。

**链接：** [官网](https://logicstamp.dev) · [GitHub](https://github.com/LogicStamp/logicstamp-mcp) · [CLI](https://github.com/LogicStamp/logicstamp-context) · [更新日志](https://github.com/LogicStamp/logicstamp-mcp/blob/main/CHANGELOG.md)

标签：AI 助手, Cilium, Context Compiler, GNU通用公共许可证, LogicStamp, MCP, MITM代理, Model Context Protocol, Node.js, NPM, TypeScript, 上下文交付, 主题上下文, 威胁情报, 安全插件, 安全通信, 开发者工具, 开源, 服务器, 架构合同, 确定性合约, 确定性架构, 组件架构, 结构化上下文, 自动化攻击