ideconnect (Bluebillshtml)

IDEConnect

一个免费的、自托管的模型上下文协议（MCP）服务器，在多个AI IDE之间提供共享的、持久的项目上下文。

什么是IDEConnect？

IDEConnect创建了一个“共享项目大脑”，以便所有IDE和AI代理都能理解相同的项目范围、架构、约束和决策 不依赖聊天记录.

关键概念：项目背景与聊天历史

IDEConnect提供项目上下文（您的项目是什么），而不是聊天历史（您讨论过的内容）。每个IDE都维护单独的对话，但所有IDE都以相同的方式理解您的项目。

示例：您在Cursor中讨论身份验证→ 聊天保持在Cursor中。你打开Kiro→ Kiro了解您的项目架构（来自IDEConnect），但看不到您的Cursor聊天。

IDEConnect提供什么

1.一致的项目理解

您的所有AI IDE（Cursor、Kiro、Antigravity、Claude Desktop）都理解：

• 项目概述-目的、范围、目标、利益相关者
• 架构-系统设计、组件、数据流、模式
• 约束-技术限制、业务规则、资源约束
• 决策-具有基本原理的架构决策
• 路线图-未来计划和里程碑

2.零手动配置

一个命令设置一切——自动检测IDE，自动配置它们，创建模板，并生成文件注入。

3.基于文件的存储

确定性、版本控制、人类可读的标记文件。无需数据库——简单、可靠、便携。

4.IDE不可知

可通过适配器与Cursor（原生MCP）、Claude Desktop（本地MCP）、Kiro（文件注入）、Antigravity（CLI适配器）和任何IDE配合使用。

5.免费和自托管

没有外部服务，没有付费API，没有云依赖关系-100%本地和私有。

安装

先决条件： Node.js 18或更高版本，npm或yarn

从npm安装（推荐）：

npm install -g ideconnect

然后在您的项目目录中：

ideconnect setup

这会自动：

1. 检查Node.js版本
2. 安装所有依赖项
3. 创造 .ideconnect/ 目录
4. 初始化上下文文件模板
5. 自动检测和配置IDE
6. 为非MCP IDE生成文件注入

安装后：

1. 在中编辑上下文文件 .ideconnect/ 要记录您的项目：

- overview.md -项目目的、范围、目标 - architecture.md -系统设计、组件 - constraints.md -技术和业务限制 - decisions.md -架构决策 - roadmap.md -未来计划（可选）

1. 重新启动IDE以加载IDEConnect

1. 开始使用上下文感知AI辅助！

IDE配置

安装脚本会自动配置Cursor和Claude Desktop。如果自动配置失败，请手动添加到IDE的配置中：

光标 -编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ideconnect": {
      "command": "node",
      "args": ["/absolute/path/to/ideconnect/server/index.js"]
    }
  }
}

克劳德桌面版 -编辑平台的配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "ideconnect": {
      "command": "node",
      "args": ["/absolute/path/to/ideconnect/server/index.js"]
    }
  }
}

非MCP IDE（Kiro、反重力等）

选项1：文件注入-IDEConnect生成 .ideconnect-context.json 自动。您的IDE可以读取此文件。

选项2:CLI适配器：

node adapters/cli/ideconnect-cli.js get-overview

运作原理

架构： AI集成开发环境→ MCP协议→ IDEConnect服务器→ .ideconnect/文件

1. IDE启动并调用MCP工具
2. IDEConnect服务器从以下位置读取markdown文件 .ideconnect/
3. 返回带有项目上下文的结构化JSON
4. AI使用上下文进行所有响应

上下文文件： IDEConnect读取来自 .ideconnect/ 目录：

• overview.md -项目概况
• architecture.md -系统架构
• constraints.md -项目限制
• decisions.md -架构决策
• roadmap.md -路线图（可选）

可用的MCP工具：

• get_project_context -获取完整的项目上下文
• get_overview -获取项目概述
• get_architecture -获取架构文档
• get_constraints -获取项目约束
• get_decisions -获得记录的决策
• get_roadmap -获取路线图（可选）

常见问题和故障排除

安装失败 - npm run install 失败

• 检查Node.js版本： node --version （必须为18+）
• 确保项目目录中的写入权限
• 如果需要，请尝试使用administrator/sudo运行
• 检查是否 .ideconnect/ 目录已存在（删除并重试）

未检测到IDE -安装程序显示“未检测到IDE”

• 这没关系-安装程序仍将尝试配置通用IDE
• 手动配置IDE（请参阅上面的IDE配置）
• 验证IDE配置文件位置是否存在

IDE未连接 -IDE未连接到IDEConnect

• 验证IDE配置中的MCP服务器路径是否与实际位置匹配（使用绝对路径）
• 检查服务器依赖关系： cd server && npm install
• 手动测试服务器： node server/index.js （应该开始时没有错误）
• 配置更改后重新启动IDE
• 检查IDE日志中的连接错误

未找到上下文文件 -MCP工具返回“找不到文件”

• 验证 .ideconnect/ 目录存在： ls .ideconnect
• 重新初始化上下文： node scripts/init.js
• 运行命令时检查您是否处于项目根目录
• 验证文件权限-确保文件可读

服务器无法启动 -MCP服务器崩溃或无法启动

• 验证已安装的依赖关系： cd server && npm install
• 检查Node.js版本： node --version （必须为18+）
• 直接测试服务器： node server/index.js （查找错误消息）
• 检查服务器代码中的文件路径是否与您的系统匹配

IDE显示旧上下文 -未反映对上下文文件的更改

• 无需重新启动-更改立即生效
• 验证文件是否正确保存
• 检查文件编码-应为UTF-8
• 如果仍不工作，请重新启动IDE

文件注入不起作用 - .ideconnect-context.json 未生成

• 手动运行： node adapters/file-inject/inject.js
• 检查 .ideconnect/ 目录存在
• 验证项目目录中的写入权限

多个项目 -如何将IDEConnect用于多个项目？

• 每个项目都有自己的 .ideconnect/ 目录
• IDEConnect向上搜索目录树以查找上下文
• 自动工作-每个项目不需要配置

团队协作 -如何与团队共享上下文？

• 提交 .ideconnect/ 转git（推荐）
• 团队成员获取更新
• 上下文文件受版本控制
• 无需同步-基于文件，确定性

隐私问题 -担心存储项目上下文

• 所有本地服务-无外部服务
• 基于文件-您控制一切
• 版本控制-使用 .gitignore 如有需要
• 无聊天记录-仅存储项目上下文

验证

检查一切是否正常：

npm run verify

这将检查：

• ✅ 上下文文件存在
• ✅ IDE配置正确
• ✅ MCP服务器已就绪
• ✅ 文件注入有效

项目结构

ideconnect/
├── server/              # MCP server implementation
│   ├── index.js         # Main server
│   ├── tools/           # Context tools
│   └── package.json     # Dependencies
├── .ideconnect/          # Context storage (created by setup)
│   ├── overview.md
│   ├── architecture.md
│   ├── constraints.md
│   ├── decisions.md
│   └── roadmap.md
├── adapters/             # IDE adapters
│   ├── cli/             # CLI wrapper
│   └── file-inject/     # File injection
├── scripts/              # Setup scripts
│   ├── setup.js         # Automated setup
│   ├── init.js          # Initialize context
│   └── verify.js        # Verification
└── README.md            # This file

需求

• Node.js：18岁或以上
• npm：任何最新版本
• 操作系统：Windows、macOS或Linux

许可证

麻省理工学院

贡献

这是一个自托管工具。根据项目的需要进行分叉、修改和使用。

支持

对于问题：

1. 查看上面的“常见问题”部分
2. 通过以下方式验证安装 npm run verify
3. 检查IDE日志中的错误消息
4. 确保已安装Node.js 18+