lineai-mcp-server

lineai-mcp-server

一个 MCP 服务，用于在 AI 编程助手中使用 Lineai 丰富的软件依赖数据。

文档

从代码生成的架构文档位于 docs/（在 LIN-737 中添加；根据 LIN-699 的变更更新 — PR #61 / neo4cape #1860）：

• docs/architecture.md — 完整的架构分析：模块图、工具接口及每个工具调用的 Lineai /api/... 端点、身份验证流程、缓存、错误处理分类、配置、打包与发布，以及发现。
• docs/architecture-diagrams.md — Mermaid 图表集（生态系统、模块图、调用序列、身份验证/缓存、错误分类）。
• docs/rendered-diagrams/ — 已提交的所有图表的 SVG 渲染文件。

组件

工具

该服务实现了 八个 工具：两个影响分析工具，以及六个由 Lineai 图谱 HTTP API 支持的 图谱 工具。

代码分析工具

• lineai-method-impact：从 Lineai 服务的 API 获取代码影响评估。
  • 接受你正在处理的给定“方法”。当简单名称可能存在于多个代码库中时，请在 class 中传入 完全限定 的类名（例如 com.acme.shell.AnalyzeCommands）：完全限定类名会精确选择该类，而匹配多个类的简单名称会返回列出候选项的歧义页面，而不会悄悄分析另一个代码库中的类。
  • 影响分析是从 Lineai 图谱影响端点执行的 有界上游遍历（depth 参数，默认值为 3，最大值为 10）。报告的 影响范围 部分会说明数据来源（图谱，或在未部署图谱端点时使用的旧版完整链路端点），以及结果是否完整（ok）或仅为下限（partial）——部分结果绝不表示“没有影响”。
• lineai-database-impact：分析代码与数据库实体之间的影响。
  • 接受数据库实体类型（列、表或视图）及其名称。

所有八个工具还接受可选的 workspace 和 materialized_view_id 参数，用于限定单次调用的范围；如果两者均未提供（且未设置 LINEAI_WORKSPACE_NAME），则会自动使用服务默认工作区的最新物化视图。

Graph API 工具

这些工具会在与 LINEAI_SERVER_HOST 相同的主机上调用 /api/ai-retrieval/graph/ 下的 POST / GET 端点，并使用与其他 MCP 工具相同的会话身份验证。如果未部署 Graph 路由，服务会返回清晰的“graph not available”（图谱不可用）提示（通常是在 HTTP 404 之后）。

• lineai-graph-capabilities：GET — 查询工作区物化视图支持的关系类型、限制和标记（materializedViewId 的解析方式与其他工具相同：显式 ID → workspace 参数 → LINEAI_WORKSPACE_NAME → 服务默认值）。
• lineai-graph-search：按文本 query / q 和／或 identity_prefix 搜索节点；可选参数包括 scan_space（扫描空间 ID 或显示名称）、prefer_latest_scan、limit。结果由服务排序（精确短名称 → 精确全限定名称 → 类似类的标签 → 文本得分 → 最新扫描）；data.hits[i] 描述 data.nodes[i]（score、matchKind、labelTier）；data.totalHitCount 是实际总数，因此如果结果达到整页，表示应“缩小查询范围”，而不是“结果不存在”。
• lineai-graph-impact：从 seed_node_ids 出发进行有界依赖关系／影响范围遍历，可使用 direction（upstream = 依赖种子节点的内容，downstream，both）和 depth（服务默认值为 3，最大为 10）。响应包含 status（ok | partial）、truncated、nodeCount、staticAnalysisGap 和 assumptionsApplied 标记；结果为部分、降级，或较旧的服务忽略了某个选项时，工具会在 JSON 上方显示提示。
• lineai-graph-path-explain：说明 from_node_id 与 to_node_id 之间的最短路径。
• lineai-graph-validate-change-scope：根据种子节点和 proposed_change_summary，为拟议更改提供启发式检查清单／风险摘要。
• lineai-graph-owners：通过 node_id 或 identity_prefix 查找节点，并显示名称中包含 "owner" 的属性字段。

MCP 架构中注明的工具参数支持 snake_case 别名（例如 materialized_view_id、seed_node_ids）；发送给 Lineai 的请求正文则使用 camelCase JSON 键。

安装

前置条件

MCP 服务依赖 Astral UV 运行，请安装

MacOS 上 uvx 的解决方法

已知 uvx 在 MacOS 上存在问题，可能导致 Lineai MCP 服务无法在某些 IDE（例如 Cursor）中启动，并出现类似以下错误： 请参阅问题 #11

Failed to connect client closed

这似乎是 Astral uvx 在 MacOS 上运行时的问题。可使用以下方法解决：

1. 在本地克隆此项目。
2. 将 mcp.json 配置为使用 uv 而不是 uvx。例如：

{
  "mcpServers": {
    "lineai-mcp-server": {
      "type": "stdio",
      "command": "<PATH_TO_UV>/uv",
      "args": [
        "--directory",
        "<PATH_TO_THIS_REPO>/lineai-mcp-server-main",
        "run",
        "lineai-mcp-server"
      ],
      "env": {
        "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
        "LINEAI_USERNAME": "<my username>",
        "LINEAI_PASSWORD": "<my password>",
        "LINEAI_WORKSPACE_NAME": "<my workspace>",
        "LINEAI_DEBUG_MODE": "true"
      }
    }
  }
}

3. 重启 Cursor。
4. 确保已设置 Lineai 的 Cursor 全局规则。
5. 打开 Cursor 中的 MCP 选项卡，并刷新 lineai-mcp-server。
6. 让 Cursor 更改现有类中的代码。此时 MCP 服务应能成功运行影响分析。

不同 IDE 的配置

Visual Studio Code 配置

要在 VS Code 中配置此 MCP 服务：

1. 首先，确保已在 VS Code 中启用 GitHub Copilot Agent 模式。

2. 在工作区中创建 .vscode/mcp.json 文件，并添加以下配置：

{
  "servers": {
    "lineai-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "lineai-mcp-server@latest"
      ],
      "env": {
        "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
        "LINEAI_USERNAME": "<my username>",
        "LINEAI_PASSWORD": "<my password>",
        "LINEAI_WORKSPACE_NAME": "<my workspace>",
        "LINEAI_DEBUG_MODE": "true"
      }
    }
  }
}

注意： 在某些系统上，可能需要使用 uvx 可执行文件的完整路径，而不仅仅是 "uvx"。例如：Linux/Mac 上的 /home/user/.local/bin/uvx，或 Windows 上的 C:\Users\username\AppData\Local\astral\uvx.exe。

3. 或者，也可以在命令面板中运行 MCP: Add Server 命令，并提供服务信息。

4. 要管理 MCP 服务，请在命令面板中使用 MCP: List Servers 命令。

5. 配置完成后，Copilot Agent 模式即可使用此服务的工具。在 Agent 模式下，可以在聊天视图中点击 Tools 按钮，按需启用或停用特定工具。

6. 要在 Agent 模式下使用 Lineai 工具，可以针对代码影响或数据库关系提出具体问题，Agent 将调用相应的工具。

Claude Desktop 配置

通过编辑配置文件来配置 Claude Desktop：

• MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

将以下内容添加到配置文件中：

"mcpServers": {
  "lineai-mcp-server": {
    "command": "uvx",
    "args": [
      "lineai-mcp-server@latest"
    ],
    "env": {
      "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
      "LINEAI_USERNAME": "<my username>",
      "LINEAI_PASSWORD": "<my password>",
      "LINEAI_WORKSPACE_NAME": "<my workspace>"
    }
  }
}

注意： 在某些系统上，可能需要使用 uvx 可执行文件的完整路径，而不仅仅是 "uvx"。例如：Linux/Mac 上的 /home/user/.local/bin/uvx，或 Windows 上的 C:\Users\username\AppData\Local\astral\uvx.exe。

添加配置后，重启 Claude Desktop 以应用更改。

Windsurf IDE 配置

要在 Windsurf IDE 中运行此 MCP 服务：

配置 Windsurf IDE：

要配置 Windsurf IDE，需要创建或修改 ~/.codeium/windsurf/mcp_config.json 配置文件。

将以下配置添加到文件中：

"mcpServers": {
  "lineai-mcp-server": {
    "command": "uvx",
    "args": [
      "lineai-mcp-server@latest"
    ],
    "env": {
      "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
      "LINEAI_USERNAME": "<my username>",
      "LINEAI_PASSWORD": "<my password>",
      "LINEAI_WORKSPACE_NAME": "<my workspace>"
    }
  }
}

注意： 在某些系统上，可能需要使用 uvx 可执行文件的完整路径，而不仅仅是 "uvx"。例如：Linux/Mac 上的 /home/user/.local/bin/uvx，或 Windows 上的 C:\Users\username\AppData\Local\astral\uvx.exe。

添加配置后，重启 Windsurf IDE 或刷新工具以应用更改。

Cursor 配置

要在 Cursor 中配置 Lineai MCP 服务：

1. 创建 .cursor/mcp.json 文件来配置 MCP 服务：

{
  "mcpServers": {
    "lineai-mcp-server": {
      "command": "uvx",
      "args": [
        "lineai-mcp-server@latest"
      ],
      "env": {
        "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
        "LINEAI_USERNAME": "<my username>",
        "LINEAI_PASSWORD": "<my password>",
        "LINEAI_WORKSPACE_NAME": "<my workspace>",
        "LINEAI_DEBUG_MODE": "true"
      }
    }
  }
}

注意： 在某些系统上，可能需要使用 uvx 可执行文件的完整路径，而不仅仅是 "uvx"。例如：Linux/Mac 上的 /home/user/.local/bin/uvx，或 Windows 上的 C:\Users\username\AppData\Local\astral\uvx.exe。

2. 重启 Cursor 以应用更改。

现在，Lineai MCP 服务工具即可在 Cursor 工作区中使用。

AI 助手指令/规则

为了帮助 AI 助手有效使用 Lineai 工具，可以将以下指令/规则添加到客户端配置中。建议根据团队的具体编码规范、最佳实践和工作流要求自定义这些指令：

当 Lineai 主机上提供图谱 API 时，请参照服务在其 MCP instructions 中已有的指导，扩展规则：使用 lineai-graph-* 工具（search、impact、path-explain、validate-change-scope、owners、capabilities）进行限定范围的图谱发现；如果图谱调用失败并提示“not available”，则回退到 lineai-method-impact / lineai-database-impact。

VS Code (GitHub Copilot) 指令

创建 .vscode/copilot-instructions.md 文件，并添加以下内容：

# Lineai MCP Server Instructions

When modifying existing code methods:
- Use lineai-method-impact to analyze code changes
- Use lineai-database-impact for database modifications
- When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
- Highlight impact results for the modified methods

When modifying SQL code or database entities:
- Always use lineai-database-impact to analyze potential impacts
- Highlight impact results for the modified database entities

To use the Lineai tools effectively:
- For code impacts: Ask about specific methods or functions
- For database relationships: Ask about tables, views, or columns
- For graph discovery: Prefer lineai-graph-* tools when available
- Review the impact results before making changes
- Consider both direct and indirect impacts

Claude Desktop 指令

创建 ~/.claude/instructions.md 文件，并添加以下内容：

# Lineai MCP Server Instructions

When modifying existing code methods:
- Use lineai-method-impact to analyze code changes
- Use lineai-database-impact for database modifications
- When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
- Highlight impact results for the modified methods

When modifying SQL code or database entities:
- Always use lineai-database-impact to analyze potential impacts
- Highlight impact results for the modified database entities

To use the Lineai tools effectively:
- For code impacts: Ask about specific methods or functions
- For database relationships: Ask about tables, views, or columns
- For graph discovery: Prefer lineai-graph-* tools when available
- Review the impact results before making changes
- Consider both direct and indirect impacts

Windsurf IDE 规则

创建或修改 ~/.codeium/windsurf/memories/global_rules.md Markdown 文件，并添加以下内容：

When modifying existing code methods:
- Use lineai-method-impact to analyze code changes
- Use lineai-database-impact for database modifications
- When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
- Highlight impact results for the modified methods

When modifying SQL code or database entities:
- Always use lineai-database-impact to analyze potential impacts
- Highlight impact results for the modified database entities

To use the Lineai tools effectively:
- For code impacts: Ask about specific methods or functions
- For database relationships: Ask about tables, views, or columns
- For graph discovery: Prefer lineai-graph-* tools when available
- Review the impact results before making changes
- Consider both direct and indirect impacts

Cursor 全局规则

要在 Cursor 中配置 Lineai 规则：

1. 打开 Cursor Settings
2. 前往“Rules”部分
3. 将以下内容添加到“User Rules”：

# Lineai MCP Server Rules
## Codebase
- The Lineai MCP Server is for java, javascript, typescript, and C# dotnet codebases
- don't run the tools on python or other non supported codebases
## AI Assistant Behavior
- When modifying existing code methods:
  - Use lineai-method-impact to analyze code changes
  - Use lineai-database-impact for database modifications
  - When the Lineai graph API is available, use lineai-graph-* tools (search, impact, path-explain, validate-change-scope, owners, capabilities) for bounded graph discovery; otherwise rely on method/database impact tools
  - Highlight impact results for the modified methods
- When modifying SQL code or database entities:
  - Always use lineai-database-impact to analyze potential impacts
  - Highlight impact results for the modified database entities
- To use the Lineai tools effectively:
  - For code impacts: Ask about specific methods or functions
  - For database relationships: Ask about tables, views, or columns
  - Review the impact results before making changes
  - Consider both direct and indirect impacts

环境变量

可以配置以下环境变量来自定义服务的行为：

• LINEAI_SERVER_HOST：Lineai 服务的 URL（必需）。所有 API 路径（/api/authenticate、/api/ai-retrieval/...、/api/dependency/...、/api/materialized-view...）都会附加到该 URL。
• LINEAI_USERNAME：你的 Lineai 用户名（必需）。
• LINEAI_PASSWORD：你的 Lineai 密码（必需）。
• LINEAI_WORKSPACE_NAME：要使用的默认工作区。可选：单次工具调用可以通过 workspace / materialized_view_id 参数覆盖此设置；如果完全没有指定任何内容，则使用服务默认工作区的最新物化视图。
• LINEAI_DEBUG_MODE：设为 true 可启用调试模式。启用后，会生成 timing_log.txt 和 impact_data*.json 等额外调试文件。默认为 false。

调优（可选 — 仅在服务启动时读取一次）

• LINEAI_TOKEN_CACHE_TTL：身份验证令牌缓存的有效期，单位为秒。默认为 3600。
• LINEAI_METHOD_CACHE_TTL：方法短名称搜索结果缓存的有效期，单位为秒。默认为 300。
• LINEAI_IMPACT_CACHE_TTL：影响分析结果缓存的有效期，单位为秒。默认为 300。
• LINEAI_MV_CACHE_TTL：物化视图解析缓存的有效期，单位为秒（工作区名称 / 服务默认值 → 视图 ID）。默认为 300。
• LINEAI_REQUEST_TIMEOUT：所有 Lineai API 调用的整体 HTTP 请求超时时间，单位为秒。默认为 120.0。图影响调用在服务端受到限制（深度 / 节点 / 关系数量上限，查询超时时间为 60 s），因此此处超时通常意味着深度过大——请尝试将 depth 设为 1–2 后重试。
• LINEAI_CONNECT_TIMEOUT：HTTP 连接超时时间，单位为秒。默认为 30.0。
• LINEAI_METHOD_IMPACT_BACKEND：graph（默认）会从有界图影响端点获取 lineai-method-impact 子图；只有在图 路由 缺失时（404 且没有 neo4cape 的实体消息），才会回退到旧版 /api/dependency/impact/full 列表。若 404 指明了节点（“Unable to locate node …”），则会报告搜索 / 视图不一致；因为从未知 ID 开始的旧版遍历会返回空结果，造成“未关联”的假象；legacy 会强制使用旧版端点（无界的完整入向链）。每次调用时读取。

仅用于测试

• LINEAI_TEST_MODE：设置后（任意值均可），服务会跳过加载 .env 文件，以便测试完全控制环境。
• LINEAI_GRAPH_E2E_REQUIRED：运行图 MCP 集成测试时设为 1，即可让缺失的图 API（HTTP 404 / “Graph API not available”）导致测试套件失败，而不是跳过这些测试。

配置示例

"env": {
  "LINEAI_SERVER_HOST": "<url to the server e.g. https://myco.app.lineai.net>",
  "LINEAI_USERNAME": "<my username>",
  "LINEAI_PASSWORD": "<my password>",
  "LINEAI_WORKSPACE_NAME": "<my workspace>",
  "LINEAI_DEBUG_MODE": "true"
}

固定版本

不使用服务的 latest 版本时，可以将 args 字段改为与 pypi 上的版本一致，从而固定到特定版本，例如：

    "args": [
      "[email protected]"
    ],

版本兼容性

此 MCP 服务有以下版本兼容性要求：

• 版本 0.3.1 及以下：与所有 Lineai API 版本兼容
• 版本 0.4.0 及以上：要求 Lineai API 版本为 25.10.0 或更高

如果要升级，请确保你的 Lineai 服务满足最低 API 版本要求。

图谱工具：要求你的 Lineai 部署在 /api/ai-retrieval/graph/ 下提供图谱端点。较旧或不完整的部署可能会返回 404；MCP 工具会将其显示为清晰的错误，而不是含糊不清的故障。

排序搜索 / 有界影响范围（LIN-870）：排序、hits、真实的 totalHitCount、scan_space / prefer_latest_scan，以及 depth / direction / status: partial 影响范围约定，都需要包含 neo4cape LIN-870 的 Lineai 服务。在较旧的服务上，这些工具仍可运行：搜索结果会按服务返回的未排序顺序显示，影响范围分析会遍历整个子图，而被忽略的选项会以 *_not_implemented / *_reserved_* 标记回传，工具会将其显示为“x 已被忽略（旧版服务）”。如果缺少图谱端点，lineai-method-impact 会自动回退到旧版影响范围端点。

调试日志

当 LINEAI_DEBUG_MODE=true 时，调试文件会写入系统临时目录：

• Windows：%TEMP%\lineai-mcp-server（通常为 C:\Users\{username}\AppData\Local\Temp\lineai-mcp-server）
• macOS：/tmp/lineai-mcp-server（如果设置了 $TMPDIR，则为 $TMPDIR/lineai-mcp-server）
• Linux：/tmp/lineai-mcp-server（如果设置了 $TMPDIR，则为 $TMPDIR/lineai-mcp-server）

调试文件包括：

• timing_log.txt - 性能计时信息
• impact_data_*.json - 用于故障排查的原始影响范围分析数据

查找日志目录：

import tempfile
import os
print("Log directory:", os.path.join(tempfile.gettempdir(), "lineai-mcp-server"))

测试

运行单元测试

此项目使用 unittest 进行测试。无需任何外部依赖即可运行单元测试：

python -m unittest discover -s test -p "unit_*.py"

单元测试使用模拟数据，无需连接 Lineai 服务。test/unit_test_handlers.py 包含 TestMethodNodeSelection 表（LIN-870 中 AnalyzeCommands 位于三个仓库的用例：完全限定类名 → 正确的仓库，简单名称 → 歧义页面，外部完全限定名称 → 未找到页面，从不选择未解析的引用），以及图谱后端 / 旧版回退 / 部分结果处理器用例；test/unit_test_graph_tools.py 覆盖部分结果说明和旧版服务标记。

集成测试（可选）

如果要运行连接真实 Lineai 服务的集成测试：

1. 将 test/.env.test.example 复制为 test/.env.test，并填入你的 Lineai 服务详情
2. 运行集成测试：

python -m unittest discover -s test -p "integration_*.py"

注意：集成测试需要访问 Lineai 服务实例。

图谱 MCP 端到端测试

test/integration_test_graph.py 会针对 LINEAI_SERVER_HOST，通过真实的 MCP 处理器路径（handle_call_tool）运行 lineai-graph-capabilities 和链式流程（搜索 → 影响范围分析 → 路径 → 验证 → 所有者）。凭据配置方式与其他集成测试相同（从 test/.env.test.example 创建 test/.env.test）。

• 如果主机未提供图谱路由，测试默认会跳过。
• 设置 LINEAI_GRAPH_E2E_REQUIRED=1，可将缺少图谱 API 转为硬性失败（适用于 CI 中必须提供图谱 API 的场景）。

在仓库根目录运行：

./scripts/run_graph_e2e.sh

等效命令：

uv run python -m unittest test.integration_test_graph -v

官方 MCP 注册表验证

mcp-name：io.github.lineai-intelligence/lineai-mcp-server