Cogna

AI 查询（MCP）

通过 Model Context Protocol 让 AI 编程工具直接读取 Cogna 索引，告别符号幻觉。

AI 查询（MCP）

MCP（Model Context Protocol）是一套开放标准，让 AI 编程助手能够通过标准化接口调用外部工具与数据源。Cogna 实现了 MCP 服务端，AI 工具可以直接查询你项目中真实存在的符号、类型与接口，而不是凭语言模型的”记忆”猜测。

工作原理

cogna build
    ↓ 生成 dist/ 索引
cogna mcp serve
    ↓ 暴露 MCP 端点
AI 工具（Claude / Cursor / ...）
    ↓ 按符号名或文本查询
返回精确签名 + 文档注释

前置条件

在启动 MCP 服务前，必须先在仓库根目录完成初始化和构建：

cogna init   # 生成 cogna.yaml
cogna build  # 构建索引（写入 dist/）

启动 MCP 服务

HTTP 模式

适合大多数支持 HTTP MCP 的工具（Cursor、OpenCode、Windsurf 等）：

cogna mcp serve --port 3000

stdio 模式

部分工具（如 Claude Code）要求通过标准输入输出通信，可直接将 cogna mcp serve --stdio 作为子进程：

cogna mcp serve --stdio

在各工具中配置

Claude Code

Claude Code 支持通过 ~/.claude.json（全局）或项目根目录下的 .claude.json 配置 MCP 服务器。

stdio 模式（推荐）：

{
  "mcpServers": {
    "cogna": {
      "command": "cogna",
      "args": ["mcp", "serve", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

HTTP 模式：

先在终端运行 cogna mcp serve --port 3000，再配置：

{
  "mcpServers": {
    "cogna": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "cogna": {
      "command": "cogna",
      "args": ["mcp", "serve", "--stdio"],
      "cwd": "${workspaceFolder}"
    }
  }
}

或使用 HTTP 模式（先启动服务再配置）：

{
  "mcpServers": {
    "cogna": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

OpenCode

OpenCode 使用项目根目录的 .opencode/mcp.json 或全局配置文件：

{
  "mcpServers": {
    "cogna": {
      "command": "cogna",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Windsurf

在 Windsurf 的设置中打开 MCP Servers，添加新条目：

  • Name：cogna
  • Transport：stdio
  • Command：cogna mcp serve --stdio
  • Working Directory：项目根目录

或通过配置文件 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "cogna": {
      "command": "cogna",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

VS Code（GitHub Copilot）

在工作区配置文件 .vscode/mcp.json 中添加：

{
  "servers": {
    "cogna": {
      "type": "stdio",
      "command": "cogna",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Zed

在 Zed 的 settings.json 中添加 context_servers 配置：

{
  "context_servers": {
    "cogna": {
      "command": {
        "path": "cogna",
        "args": ["mcp", "serve", "--stdio"]
      }
    }
  }
}

Continue.dev

在 .continue/config.json 中添加：

{
  "mcpServers": [
    {
      "name": "cogna",
      "command": "cogna",
      "args": ["mcp", "serve", "--stdio"]
    }
  ]
}

其他支持 MCP 的工具

凡是支持 MCP 标准的工具，均可通过以下两种方式之一接入：

  • stdio：使用 cogna mcp serve --stdio 作为子进程命令
  • HTTP：先运行 cogna mcp serve --port <PORT>，然后将端点配置为 http://localhost:<PORT>

可用的 MCP 工具

Cogna MCP 服务端对外暴露以下工具，AI 助手可以直接调用：

工具名说明
fetch_packages获取仓库的完整包依赖树
query_outlines列举指定包的所有公开符号概要
query按 ID、符号名或自由文本搜索符号，支持翻页

使用示例

配置好 MCP 后，你可以直接在 AI 助手的对话框中用自然语言发出查询：

「查询 github.com/example/mylib 中所有关于 Parse 的公开函数」

「HandleRequest 函数的签名是什么？有哪些参数？」

「列出 pkg:golang/github.com/gin-gonic/gin@v1.9.0 里所有已废弃的方法」

AI 工具会自动调用对应的 MCP 工具，返回精确的签名与文档注释，无需你手动翻代码。

常见问题

查不到符号怎么办？

  1. 确认已执行 cogna build（dist/ 目录存在且为最新）
  2. 确认查询的目标是公开声明，而非私有实现细节
  3. 多包仓库中，确认 package 参数使用了完整的 PURL

stdio 模式下工具无响应

检查 cogna 是否在 PATH 中：

which cogna

如果不在，在工具配置中改用绝对路径（如 /usr/local/bin/cogna）。

索引更新后 AI 仍返回旧结果

部分工具会在会话期间缓存 MCP 响应。重启工具或开启新对话，AI 即可读取最新索引。

相关文档

PreviousSKILLNextCI & CD