项目简介

Koopa 是一个功能强大的终端AI助手，它不仅能管理本地知识库和会话历史，还能通过其内置工具执行文件操作、系统命令和网络请求。最重要的是，Koopa 支持 Model Context Protocol (MCP) 规范，可以作为 MCP 服务器，使其功能轻松被 Claude Desktop、Cursor 和 Gemini CLI 等 LLM 客户端调用。

主要功能点

本地知识库管理: 索引您的文档，实现上下文感知的对话。
会话持久化: 自动保存所有对话，方便随时恢复和回顾。
内置工具: 提供安全的文件读写、目录列表、文件删除、文件信息获取、执行系统命令、获取环境变量、网络搜索和网页内容抓取等功能。
MCP 集成: 兼容 MCP 客户端，如 Claude Desktop, Cursor, 和 Gemini CLI，允许这些客户端调用 Koopa 的工具。
HTTP API: 提供编程接口，方便自动化和集成到其他应用。
强化安全: 内置路径遍历、命令注入、SSRF (服务器端请求伪造) 和敏感环境变量访问防护，确保工具调用安全。

安装步骤

前提条件:
- Go 1.24+ (安装说明：https://go.dev/doc/install)
- Docker (安装说明：https://docs.docker.com/get-docker/)
- Gemini API 密钥 (从 ai.google.dev 获取)

克隆仓库并编译: 在您的终端中执行以下命令：

git clone https://github.com/Koopa0/koopa-cli.git
cd koopa-cli
go build -o koopa

这将在当前目录下生成名为 'koopa' 的可执行文件。

启动数据库: Koopa 使用 PostgreSQL 进行数据存储。请确保 Docker 正在运行。
```
docker-compose up -d
```
这将启动一个 PostgreSQL 数据库容器，并在后台运行。

运行 Koopa (作为AI助手): 设置您的 Gemini API 密钥，然后运行 Koopa。

export GEMINI_API_KEY=your-api-key # 将 'your-api-key' 替换为您的实际 Gemini API 密钥
./koopa

现在您可以在终端中与 Koopa 助手进行交互了。

MCP 服务器配置

作为 MCP 服务器，Koopa 可以被外部 MCP 客户端（如 Genkit CLI, Cursor, Claude Desktop）调用。您的 MCP 客户端需要配置 Koopa 服务器的启动命令。

以下是 Koopa MCP 服务器的配置信息示例（通常以 JSON 格式提供给 MCP 客户端）：

{
  "name": "koopa-cli-mcp",
  "description": "Koopa CLI 提供的文件、系统和网络工具",
  "command": "koopa",
  "args": ["mcp"],
  "environment": {
    "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
  },
  "timeout": 30
}

'name': 'koopa-cli-mcp' - MCP 服务器在客户端显示的名称。
'description': 'Koopa CLI 提供的文件、系统和网络工具' - MCP 服务器功能的简要描述。
'command': 'koopa' - 启动 Koopa MCP 服务器的可执行文件路径。假设 'koopa' 可执行文件在 PATH 环境变量中，或指定为绝对路径。
'args': '["mcp"]' - 传递给 'koopa' 命令的参数。'mcp' 参数指示 Koopa 以 MCP 服务器模式启动。
'environment':
- 'GEMINI_API_KEY': 'YOUR_GEMINI_API_KEY' - 启动 Koopa MCP 服务器所需的 Gemini API 密钥。请务必替换为您自己的实际密钥。
'timeout': '30' - (可选) 客户端等待 MCP 服务器启动的最长时间（秒）。

基本使用方法

在您的 MCP 客户端中配置上述信息并启动 Koopa MCP 服务器后，您的客户端即可通过 MCP 协议（通常是 JSON-RPC）调用 Koopa 提供的各种工具。例如，一个 LLM 代理可以调用 Koopa 的 'read_file' 工具来读取文件内容，调用 'execute_command' 来安全地执行系统命令，或者调用 'web_search' 来进行网络搜索。

示例 (LLM 客户端调用伪代码): 假设一个 LLM 代理需要了解当前目录下的文件：

LLM 代理: "我需要查看项目目录中的文件列表。"

// LLM 客户端将生成一个 MCP JSON-RPC 请求，发送给 Koopa MCP 服务器
// 请求方法: tools/call
// 请求参数:
{
  "name": "list_files",
  "arguments": {
    "path": "./"
  }
}
// Koopa MCP 服务器处理请求后，会返回文件列表信息给 LLM 客户端

关键词

项目简介

主要功能点

安装步骤

MCP 服务器配置

基本使用方法

信息