使用说明

人工智能个人知识库MCP

本文档概述了AI个人知识库MCP的设置、使用和配置，这是一个旨在管理您的长期记忆和知识库并与之交互的综合系统。它利用文本嵌入进行语义搜索、相似性比较，并在PostgreSQL数据库中使用Pgvector进行高效存储。

1.导言

AI个人知识库MCP是一个FastAPI应用程序，它利用句子转换器将文本转换为密集的数字向量（嵌入）。然后，这些嵌入可用于语义搜索、相似性比较和Pgvector等向量数据库中的聚类等任务。

2.特点

文本嵌入生成： 将输入文本转换为高维向量表示。
健康检查端点： 提供一个简单的端点来检查服务的状态和加载的模型。
Pgvector集成： 旨在使用Pgvector扩展与PostgreSQL数据库无缝协作，以实现高效的向量存储和相似性搜索。
SQL查询执行： 允许直接对内存数据库执行SQL查询。
内存相似性搜索： 便于根据文本输入搜索类似的内存记录。
内存CRUD操作： 支持创建、读取、更新和删除内存记录。

3.嵌入模型

该服务目前使用 all-mpnet-base-v2 句子转换器模型，它产生 768维 嵌入。

尺寸说明： 虽然该服务最初配置为使用 diwank/dfe-base-en-1 模型中，该模型出现了“输入未指定任何键，allow_vempty_key为False”错误。通过将输入作为字典传递来解决这个问题 [{"text": data.text}] 到 model.encode()然而为了更广泛的兼容性和稳定性， all-mpnet-base-v2 （768维）目前正在使用中。

4.设置

先决条件

Docker： 确保Docker已安装并在您的系统上运行。
Gemini CLI： 与服务交互需要Gemini命令行界面。
PostgreSQL与Pgvector： PostgreSQL数据库 pgvector 已安装并启用扩展。

环境变量

在运行应用程序之前，您需要创建一个 .env 项目根目录中的文件，用于存储您的配置。

创建一个名为的文件 .env.
将下面的模板复制到文件中，并用您的实际凭据替换占位符值。

.env 模板：

POSTGRES_HOST=your_postgres_host
POSTGRES_PORT=5432
POSTGRES_DATABASE=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secret_password

变量描述：

POSTGRES_HOST：PostgreSQL服务器的主机名或IP地址（例如。， localhost 或 PgVectorDB).
POSTGRES_PORT：PostgreSQL服务器运行的端口（默认为 5432).
POSTGRES_DATABASE：要连接的数据库的名称。
POSTGRES_USER：PostgreSQL数据库的用户名。
POSTGRES_PASSWORD：指定用户的密码。这应该保密。

Docker命令

按照以下步骤使用Docker构建和运行嵌入服务：

构建Docker镜像：
```
docker build -t embedding-mcp .
```
此命令构建Docker映像并将其标记为 embedding-mcp.
运行Docker容器：
```
docker run -d --name embedding-mcp -p 8000:8000 embedding-mcp
```
此命令以分离模式运行容器(-d)，命名它 embedding-mcp，并将容器的端口8000映射到主机上的端口8000。
停止Docker容器：
```
docker stop embedding-mcp
```
移除Docker容器：
```
docker rm embedding-mcp
```

PostgreSQL数据库设置

确保你的PostgreSQL数据库有 pgvector 启用了扩展，并配置了一个表来存储嵌入。这 memory 表在此上下文中使用：

启用Pgvector扩展：
```
CREATE EXTENSION IF NOT EXISTS vector;
```

memory 表架构： 这 memory 该表旨在存储长期内存条目。这 embedding 列对于相似性搜索至关重要。

CREATE TYPE memory_scope AS ENUM ('personal', 'project', 'global');
CREATE TYPE memory_category AS ENUM ('Code', 'Idea', 'Instruction', 'Fix', 'Doc', 'Other');

CREATE TABLE memory (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding VECTOR(768) NOT NULL, -- Current dimension is 768
    scope memory_scope NOT NULL DEFAULT 'personal',
    project TEXT,
    category memory_category,
    tags TEXT[],
    source TEXT,
    priority INTEGER DEFAULT 0,
    status memory_status DEFAULT 'active',
    usage_count INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    last_used_at TIMESTAMP WITH TIME ZONE
);

创建HNSW索引以进行相似性搜索： 为了高效地进行相似性搜索，应在以下位置创建HNSW（分层导航小世界）索引 embedding 列。这大大加快了涉及 <=> （余弦距离）运算符。
```
CREATE INDEX ON memory USING hnsw (embedding vector_cosine_ops);
```

5.API终点

人工智能个人知识库MCP公开了以下API端点：

5.1.GET/健康

说明： 检查服务的运行状况和状态，包括嵌入模型是否已加载。

答复：

{
    "status": "ok",
    "model_loaded": true,
    "model_name": "all-mpnet-base-v2"
}

5.2.POST/嵌入

说明： 为提供的输入文本生成高质量的文本嵌入。

请求正文（application/json）：

{
    "text": "The string of text to generate an embedding for."
}

响应（应用程序/json）：

{
    "embedding": [0.1, 0.2, ..., 0.N], // N is the dimension of the embedding (e.g., 768)
    "model": "all-mpnet-base-v2"
}

5.3.POST/db_query

说明： 对连接的PostgreSQL数据库执行原始SQL查询。

请求正文（application/json）：

{
    "query": "SELECT * FROM public.memory LIMIT 5;"
}

响应（应用程序/json）：
- 对于 SELECT 查询：一个JSON对象数组，其中每个对象代表一行。
- 对于 INSERT, UPDATE, DELETE 查询：
```
{
    "status": "success",
    "rows_affected": 1
}
```

5.4.POST/mem_相似性

说明： 在中执行相似性搜索 memory 基于查询文本的表。它为查询文本生成一个嵌入，然后找到最相似的内存记录。

请求正文（application/json）：

{
    "query_text": "Your search query here",
    "top_k": 5
}

响应（应用程序/json）： 一个JSON对象数组，每个对象代表一个类似的内存记录，并添加一个 similarity 分数。

5.5.POST/mem_crud

说明： 在中插入新的内存记录或更新现有的内存记录 memory 桌子。它会自动为 content 现场。

请求正文（application/json）：

{
    "id": null, // Optional: Provide ID for update, omit for insert
    "title": "My New Memory",
    "content": "This is the content of my new memory.",
    "scope": "personal",
    "project": "AI_Personal_Knowledge_Base_MCP",
    "category": "Idea",
    "tags": ["AI", "memory"],
    "source": "Gemini CLI",
    "priority": 1,
    "status": "active",
    "usage_count": 0,
    "created_at": null,
    "updated_at": null,
    "last_used_at": null
}

响应（应用程序/json）：

插入：

{
    "status": "success",
    "id": 123,
    "operation": "insert"
}

更新：

{
    "status": "success",
    "id": 123,
    "operation": "update",
    "rows_affected": 1
}

6.使用Gemini CLI

Gemini CLI通过定义的工具与嵌入服务交互。

生成嵌入

使用 generate_embedding_embed_post 为给定文本生成嵌入的工具：

<tool_code>
print(default_api.generate_embedding_embed_post(text = "Your text here"))
</tool_code>

执行相似性搜索

在您的数据库中执行相似性搜索 memory 表：

为您的查询生成嵌入：

<tool_code>
print(default_api.generate_embedding_embed_post(text = "Your search query here"))
</tool_code>

复制 embedding 从输出中提取数组。

执行SQL查询： 使用 execute_sql 使用生成的嵌入和 <=> 余弦距离运算符。替换 [YOUR_QUERY_EMBEDDING] 使用实际的嵌入阵列。
```
<tool_code>
print(default_api.execute_sql(sql = "SELECT id, title, content, embedding <=> ARRAY[YOUR_QUERY_EMBEDDING]::vector(768) AS similarity FROM postgres.public.memory ORDER BY similarity LIMIT 5;"))
</tool_code>
```
注：确保 postgres.public.memory 匹配您的数据库、模式和表名。

7.故障排除

“嵌入生成过程中出错：输入未指定任何键，allow_vempty_key为False”：此错误通常发生在 diwank/dfe-base-en-1 模型需要一个类似字典的输入。修复涉及修改 app.py 将输入传递为 [{"text": data.text}] 到 model.encode().
缓慢的相似性搜索： 如果相似性搜索速度较慢，请确保您已在您的 embedding 列，如PostgreSQL设置部分所述。对于非常小的表，PostgreSQL可能不会使用索引，但随着数据的增长，它会变得有效。
“未提供有效的会话ID”：此错误表示存在问题 FastApiMCP 集成需要一个未提供的会话ID。这通常需要外部配置或绕过 FastApiMCP 用于直接工具调用。

8.Gemini CLI配置

要将嵌入服务与Gemini CLI一起使用，您需要配置 mcpServers 在你的 settings.json 文件。这允许CLI将工具调用路由到正在运行的Docker容器。

将以下配置添加到您的 settings.json:`

"mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": [
        "mcp",
        "gateway",
        "run"
      ]
    },
    "embedding": {
      "httpUrl": "http://localhost:8000/mcp"
    }
}

MCP_DOCKER：此条目定义了一个通过Docker运行MCP网关的命令。
embedding：此条目指向嵌入服务的HTTP URL，使其工具可供Gemini CLI使用。

使用此配置，您可以调用 generate_embedding_embed_post 工具和其他工具直接从Gemini CLI嵌入服务。

9.未来的增强功能

批量嵌入生成： 实现嵌入生成的批处理，以提高处理多个文本输入时的效率。这将需要修改嵌入服务API以接受文本列表。
优化数据库插入： 探索将数据批量插入PostgreSQL数据库的更优化方法，例如使用 COPY 命令或批处理 INSERT 声明。

使用说明

人工智能个人知识库MCP

1.导言

2.特点

3.嵌入模型

4.设置

先决条件

环境变量

Docker命令

PostgreSQL数据库设置

5.API终点

5.1.GET/健康

5.2.POST/嵌入

5.3.POST/db_query

5.4.POST/mem_相似性

5.5.POST/mem_crud

6.使用Gemini CLI

生成嵌入

执行相似性搜索

7.故障排除

8.Gemini CLI配置

9.未来的增强功能

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

Obsidian笔记搜索服务