内容
# NexMemory MCP 服务器
<div align="center">
**NexMemory 知识库协议服务器**
*知识库与实体管理系统*
[](https://www.npmjs.com/package/nexmemory-mcp)
[](https://nodejs.org/)
[](LICENSE)
[安装](#installation) • [配置](#configuration) • [使用](#usage) • [功能](#features)
</div>
---
## 📋 目录
- [概述](#overview)
- [功能](#features)
- [安装](#installation)
- [配置](#configuration)
- [Cursor IDE](#cursor-ide)
- [Claude Desktop](#claude-desktop)
- [Windsurf](#windsurf)
- [Visual Studio Code (VS Code)](#visual-studio-code-vs-code)
- [GitHub Copilot](#github-copilot)
- [Zed](#zed)
- [Continue.dev](#continuedev)
- [Cline](#cline)
- [Roo Code](#roo-code)
- [Zencoder](#zencoder)
- [Sourcegraph Amp](#sourcegraph-amp)
- [环境变量](#environment-variables)
- [可用工具](#available-tools)
- [使用示例](#usage-examples)
- [故障排除](#troubleshooting)
- [许可证](#license)
---
## 🎯 概述
NexMemory MCP 服务器是一个模型上下文协议（MCP）服务器，提供 NexMemory 知识库与 AI 驱动的开发环境之间的无缝集成。它使 AI 助手能够直接在您最喜欢的代码编辑器中创建、管理、搜索和与知识库中的实体交互。
---
## ✨ 功能
- 🚀 **零配置部署**，通过 `npx` 部署
- 🔌 **通用兼容性**，与所有主要 MCP 客户端兼容
- 📝 **完整的 CRUD 操作**，适用于实体
- 🔍 **语义搜索** 功能
- 🏷️ **基于标签的过滤** 和组织
- ⚡ **与 AI 助手实时集成**
- 🔐 **安全的 API 密钥身份验证**
- 📊 **全面的实体管理**
---
## 📦 安装
### 快速开始（推荐）
直接运行，无需安装：
```bash
npx nexmemory-mcp
```
### 全局安装
```bash
npm install -g nexmemory-mcp
```
然后运行：
```bash
nexmemory-mcp
```
---
## ⚙️ 配置
### 环境变量
在配置 MCP 客户端之前，请设置以下环境变量：
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `NEXMEMORY_API_KEY` | ✅ 是 | - | 您的 NexMemory API 密钥 |
| `NEXMEMORY_API_URL` | ❌ 否 | `http://localhost:3000/api` | API 基本 URL |
| `DEBUG` | ❌ 否 | `false` | 启用调试日志记录 (`true`/`false`) |
---
## 🔧 MCP 客户端配置
### Cursor IDE
Cursor 是一个具有内置 MCP 支持的 AI 驱动代码编辑器。
#### 配置步骤
1. **定位配置文件：**
- **项目特定**：`.cursor/mcp.json` 在您的项目根目录
- **全局**：`~/.cursor/mcp.json`
2. **添加配置：**
```json
{
"mcpServers": {
"nexmemory": {
"command": "npx",
"args": [
"-y",
"nexmemory-mcp"
],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api",
"DEBUG": "false"
}
}
}
}
```
3. **重启 Cursor** 以应用更改。
---
### Claude Desktop
Claude Desktop 提供全面的 MCP 支持，具有深度集成能力。
#### 配置步骤
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. **添加配置：**
```json
{
"mcpServers": {
"nexmemory": {
"command": "npx",
"args": [
"-y",
"nexmemory-mcp"
],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api"
}
}
}
}
```
3. **重启 Claude Desktop** 以加载新配置。
---
### Windsurf
Windsurf 是一个具有内置 MCP 支持和 AI Flow 系统的 AI 原生 IDE。
#### 配置步骤
1. **定位配置文件：**
- `~/.codeium/windsurf/mcp_config.json`
2. **添加配置：**
```json
{
"mcpServers": {
"nexmemory": {
"command": "npx",
"args": [
"-y",
"nexmemory-mcp"
],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api"
}
}
}
}
```
3. **重启 Windsurf** 以应用更改。
---
### Visual Studio Code (VS Code)
VS Code 通过各种扩展支持 MCP。请选择最适合您工作流的扩展。
#### 选项 1：使用 VSCode MCP Bridge 扩展
1. **安装扩展：**
- 在 VS Code 扩展市场中搜索“VSCode MCP Bridge”
- 由 YuTengjing 安装该扩展
2. **配置 MCP 服务器：**
- 在您的工作区中创建 `.vscode/mcp.json`：
```json
{
"servers": {
"nexmemory": {
"command": "npx",
"args": ["-y", "nexmemory-mcp"],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api"
}
}
}
}
```
3. **启用代理模式：**
- 打开命令面板 (`Ctrl+Shift+P` / `Cmd+Shift+P`)
- 选择 `MCP: Add Server`
- 从列表中选择 `nexmemory`
#### 选项 2：使用 GitHub Copilot 与 MCP
1. **安装 Copilot MCP Search 扩展：**
```bash
# 通过 VS Code 扩展
# 搜索： "Copilot MCP Search"
```
2. **通过扩展设置配置：**
- 将 `nexmemory-mcp` 添加为新的 MCP 服务器
- 在扩展设置中配置环境变量
---
### GitHub Copilot
GitHub Copilot 与 MCP 服务器集成，以增强代码建议。
#### 配置步骤
1. **安装 Copilot MCP Search 扩展：**
```bash
# 通过 VS Code 扩展市场
# 搜索： "Copilot MCP Search"
```
2. **配置 MCP 服务器：**
- 打开扩展设置
- 将 `nexmemory-mcp` 添加为新的服务器
- 设置环境变量：
- `NEXMEMORY_API_KEY`
- `NEXMEMORY_API_URL`
3. **重启 VS Code** 以应用更改。
---
### Zed
Zed 是一个具有内置 MCP 支持的高性能代码编辑器。
#### 配置步骤
1. **打开设置：**
- 按 `cmd+,` (macOS) 或 `Ctrl+,` (Windows/Linux)
- 或使用命令面板： `zed: open settings`
2. **添加配置：**
```json
{
"mcpServers": {
"nexmemory": {
"command": "npx",
"args": ["-y", "nexmemory-mcp"],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api"
}
}
}
}
```
3. **重启 Zed** 以应用更改。
---
### Continue.dev
Continue 是一个适用于 VS Code 和 JetBrains IDE 的开源自动驾驶仪。
#### 配置步骤
1. **安装 Continue 扩展：**
- VS Code： 在扩展中搜索“Continue”
- JetBrains： 从 JetBrains 市场安装
2. **配置 MCP 服务器：**
- 打开 Continue 设置
- 导航到 MCP 服务器部分
- 添加配置：
```json
{
"mcpServers": {
"nexmemory": {
"command": "npx",
"args": ["-y", "nexmemory-mcp"],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api"
}
}
}
}
```
3. **重启您的 IDE** 以应用更改。
---
### Cline
Cline 是一个将 AI 模型与 MCP 支持集成的 VS Code 扩展。
#### 配置步骤
1. **安装 Cline 扩展：**
- 在 VS Code 扩展市场中搜索“Cline”
- 安装扩展
2. **配置 MCP 服务器：**
- 在您的项目根目录中创建 `.cline/mcp.json`：
```json
{
"mcpServers": {
"nexmemory": {
"command": "npx",
"args": ["-y", "nexmemory-mcp"],
"env": {
"NEXMEMORY_API_KEY": "your-api-key-here",
"NEXMEMORY_API_URL": "http://localhost:3000/api"
}
}
}
}
```
3. **重启 VS Code** 以应用更改。
---
### Roo Code
Roo Code 是一个用于 AI 驱动代码辅助的 VS Code 扩展。
#### 配置步骤
1. **安装 Roo Code 扩展：**
- 在 VS Code 扩展市场中搜索“Roo Code”
2. **配置 MCP 服务器：**
- 打开 Roo Code 设置
- 添加 MCP 服务器配置并设置环境变量
- 使用与 Cline 相同的配置格式
---
### Zencoder
Zencoder 是一个适用于 VS Code 和 JetBrains IDE 的编码代理。
#### 配置步骤
1. **安装 Zencoder：**
- VS Code：在扩展中搜索“Zencoder”
- JetBrains：从 JetBrains 市场安装
2. **配置 MCP 服务器：**
- 打开 Zencoder 设置
- 导航到 MCP 配置
- 添加 `nexmemory-mcp` 并设置环境变量
---
### Sourcegraph Amp
Sourcegraph Amp 在 VS Code、Cursor 和 Windsurf 上支持 MCP。
#### 配置步骤
1. **安装 Sourcegraph Amp：**
- 为您的编辑器安装适当的扩展
2. **配置 MCP 服务器：**
- 打开 Sourcegraph 设置
- 添加 MCP 服务器配置
- 设置 NexMemory API 的环境变量
---
## 🔑 环境变量
在您的 MCP 客户端配置中配置这些环境变量：
```bash
# 必需
NEXMEMORY_API_KEY=your-api-key-here
# 可选（默认）
NEXMEMORY_API_URL=http://localhost:3000/api
DEBUG=false
```
---
## 🛠️ 可用工具
NexMemory MCP 服务器提供以下工具：
### `create_entity`
在知识库中创建新实体。
**参数：**
- `name` （必填）：实体名称
- `description` （可选）：详细描述
- `tags` （必填）：标签名称数组
- `properties` （可选）：自定义键值对
### `get_entity`
通过 ID 检索实体。
**参数：**
- `id` （必填）：实体的 UUID
### `update_entity`
更新现有实体。
**参数：**
- `id` （必填）：实体的 UUID
- `name` （可选）：更新的名称
- `description` （可选）：更新的描述
- `tags` （可选）：更新的标签数组
- `properties` （可选）：更新的属性对象
### `delete_entity`
从知识库中删除实体。
**参数：**
- `id` （必填）：实体的 UUID
### `list_entities`
列出实体，可选过滤和分页。
**参数：**
- `limit` （可选，默认：50）：最大实体数量
- `offset` （可选，默认：0）：跳过的实体数量
- `tags` （可选）：按标签过滤（全部必须匹配）
### `search_entities`
对知识库进行语义搜索。
**参数：**
- `query` （必填）：自然语言搜索查询
- `limit` （可选，默认：10）：最大结果数量
---
## 💡 使用示例
### 示例 1：创建实体
```json
{
"name": "Project Alpha",
"description": "一个革命性的 AI 驱动项目管理系统",
"tags": ["project", "ai", "management"],
"properties": {
"status": "active",
"priority": "high"
}
}
```
### 示例 2：搜索实体
```json
{
"query": "Find all active projects related to AI",
"limit": 20
}
```
### 示例 3：更新实体标签
```json
{
"id": "entity-uuid-here",
"tags": ["project", "ai", "management", "active"]
}
```
---
## 🐛 故障排除
### 常见问题
#### 服务器无法启动
- **问题**：MCP 服务器无法启动
- **解决方案**：
- 验证 Node.js 版本：`node --version` （需要 ≥14.0.0）
- 检查 API 密钥是否正确设置
- 验证 NexMemory API 服务器正在运行
#### 连接错误
- **问题**：无法连接到 NexMemory API
- **解决方案**：
- 验证 `NEXMEMORY_API_URL` 是否正确
- 检查 API 服务器是否可访问
- 确保 API 密钥有效
#### 工具未出现
- **问题**：工具在客户端不显示
- **解决方案**：
- 重启您的 MCP 客户端应用程序
- 检查配置文件语法（有效的 JSON）
- 启用调试模式：`DEBUG=true` 以查看日志
### 调试模式
启用调试日志记录以排除问题：
```json
{
"env": {
"DEBUG": "true"
}
}
```
调试日志将出现在您的终端/控制台中。
---
## 📚 其他资源
- [模型上下文协议文档](https://modelcontextprotocol.io)
- [NexMemory 文档](https://github.com/yourusername/nexmemory)
- [MCP 客户端兼容性](https://docs.stacklok.com/toolhive/reference/client-compatibility)
---
## 📄 许可证
该项目根据 [MIT 许可证](LICENSE) 授权。
---
<div align="center">
**由 ❤️ 为 AI 开发社区打造**
[报告问题](https://github.com/yourusername/nexmemory-mcp/issues) • [请求功能](https://github.com/yourusername/nexmemory-mcp/issues) • [贡献](https://github.com/yourusername/nexmemory-mcp/pulls)
</div>
