@geekmai/anteey-mcp-client/docs/INSTALL.md

Anteey MCP 客户端 - 连接外部 AI 工具与 Anteey 笔记应用

# 安装与配置指南

## 📦 系统要求

- **Node.js**: 18.0 或更高版本
- **npm**: 8.0 或更高版本
- **Anteey 应用**: 最新版本，并启用 MCP 服务

## 🚀 安装步骤

### 方法 1：使用 npm 安装（推荐）

```bash
# 全局安装
npm install -g anteey-mcp-client

# 验证安装
anteey-mcp --version
```

### 方法 2：从源码构建

```bash
# 克隆仓库
git clone https://github.com/anteey/anteey-mcp-client.git
cd anteey-mcp-client

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接
npm link
```

## ⚙️ 初始配置

### 1. 启动 Anteey 应用

确保 Anteey 应用正在运行，并在设置中启用 MCP 服务：

1. 打开 Anteey 应用
2. 进入 **设置** > **MCP 服务**
3. 启用 MCP 服务
4. 复制 API 密钥

### 2. 配置 MCP 客户端

#### 自动配置（推荐）

```bash
# 自动发现 Anteey 服务
anteey-mcp discover

# 按提示完成配置
anteey-mcp config
```

#### 手动配置

```bash
# 启动配置向导
anteey-mcp config

# 或直接设置参数
anteey-mcp config --api-key "anteey_your_api_key_here"
anteey-mcp config --server "http://localhost:43211/api/mcp"
```

### 3. 测试连接

```bash
anteey-mcp test
```

如果看到 "✅ 所有测试通过！" 消息，说明配置成功。

## 🔧 外部工具集成

### Raycast 集成

1. **启动适配器**：

   ```bash
   anteey-mcp raycast
   ```

2. **保持运行**：适配器需要持续运行以响应 Raycast 的请求

3. **在 Raycast 中使用**：
   - 搜索 "Anteey" 相关命令
   - 使用自然语言查询笔记内容

### Cursor 集成

1. **配置 Cursor**：
   在 Cursor 的设置文件中添加 MCP 服务器配置：

   ```json
   {
     "mcp": {
       "servers": {
         "anteey": {
           "command": "anteey-mcp",
           "args": ["cursor"]
         }
       }
     }
   }
   ```

2. **重启 Cursor**：重启 Cursor 应用以加载配置

3. **使用工具**：
   - 在聊天中使用 `@anteey` 提及工具
   - 使用 `search_notes`, `get_note`, `get_recent_notes` 等函数

### Claude Desktop 集成

1. **编辑配置文件**：

   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   **Linux**: `~/.config/claude/claude_desktop_config.json`

2. **添加 MCP 服务器**：

   ```json
   {
     "mcpServers": {
       "anteey": {
         "command": "anteey-mcp",
         "args": ["claude"]
       }
     }
   }
   ```

3. **重启 Claude Desktop**：重启应用以加载配置

4. **使用工具**：
   - 在对话中直接询问关于笔记的问题
   - Claude 会自动调用相关工具搜索你的笔记

## 🔍 使用示例

### 搜索笔记

```bash
# 在 Raycast 中
"搜索包含 JavaScript 的笔记"

# 在 Cursor 中
@anteey search_notes({ query: "JavaScript", limit: 10 })

# 在 Claude Desktop 中
"帮我找一下关于 JavaScript 的笔记"
```

### 获取特定笔记

```bash
# 获取指定 ID 的笔记
get_anteey_note({ noteId: "note_123456" })
```

### 获取最近笔记

```bash
# 获取最近更新的笔记
get_recent_anteey_notes({ limit: 5 })
```

## 📊 配置参数详解

### 配置文件位置

- **macOS/Linux**: `~/.anteey-mcp/config.json`
- **Windows**: `%USERPROFILE%\.anteey-mcp\config.json`

### 配置参数说明

```json
{
  "apiKey": "anteey_your_api_key_here",
  "serverUrl": "http://localhost:43211/api/mcp",
  "timeout": 30000,
  "retries": 3,
  "logLevel": "info"
}
```

| 参数        | 类型   | 说明                                       | 默认值                           |
| ----------- | ------ | ------------------------------------------ | -------------------------------- |
| `apiKey`    | string | Anteey API 密钥，必须以 `anteey_` 开头     | -                                |
| `serverUrl` | string | Anteey MCP 服务器地址                      | `http://localhost:43211/api/mcp` |
| `timeout`   | number | HTTP 请求超时时间（毫秒）                  | `30000`                          |
| `retries`   | number | 请求失败重试次数                           | `3`                              |
| `logLevel`  | string | 日志级别：`error`, `warn`, `info`, `debug` | `info`                           |

## 🐛 故障排除

### 常见问题

#### 1. "无法连接到 Anteey 服务器"

**解决方案**：

- 确保 Anteey 应用正在运行
- 检查 MCP 服务是否已启用
- 验证服务器地址和端口是否正确

#### 2. "API 密钥验证失败"

**解决方案**：

- 检查 API 密钥是否正确
- 确保密钥以 `anteey_` 开头
- 在 Anteey 应用中重新生成 API 密钥

#### 3. "搜索结果为空"

**解决方案**：

- 检查搜索关键词是否正确
- 确保 Anteey 中有对应的笔记内容
- 尝试更宽泛的搜索词

#### 4. "外部工具无法识别 MCP 服务"

**解决方案**：

- 确保适配器正在运行
- 检查外部工具的 MCP 配置
- 重启外部工具应用

### 日志调试

启用详细日志：

```bash
anteey-mcp config
# 设置 logLevel 为 "debug"
```

查看日志文件：

```bash
# 查看配置
anteey-mcp config --list

# 运行测试并查看详细输出
anteey-mcp test
```

## 🔄 更新和维护

### 更新客户端

```bash
# 检查当前版本
anteey-mcp --version

# 更新到最新版本
npm update -g anteey-mcp-client
```

### 重置配置

```bash
# 重置为默认配置
anteey-mcp config --reset

# 重新运行配置向导
anteey-mcp config
```

## 🆘 获取帮助

如果遇到问题，请尝试以下方法：

1. **查看文档**：阅读 [README.md](../README.md) 和此安装指南
2. **运行诊断**：使用 `anteey-mcp test` 检查连接状态
3. **查看日志**：启用 debug 日志级别查看详细信息
4. **提交问题**：在 GitHub Issues 中报告问题
5. **联系支持**：发送邮件至 support@anteey.com

---

**祝你使用愉快！** 🎉