你的 AI 智能体在每次会话之间都会遗忘一切。Connapse 解决了这个问题。
每当你开始一段新的对话，你的 AI 智能体都是从零开始的——没有过去研究的记忆，无法访问你的文档，也没有积累的知识。Connapse 是一个开源的知识后端，为智能体提供持久、可搜索的记忆。上传文档，或将其指向你现有的 Amazon S3 存储桶、Azure Blob 存储容器或本地文件系统。智能体可以通过 11 个 MCP 工具、REST API 或 CLI 查询并构建自己的研究语料库。容器隔离、混合搜索（向量+关键词）、自托管且私密。使用 Docker 60 秒即可部署。基于 .NET 10 构建。
AI 智能体通过 MCP 服务器查询你的知识库，并接收带有文档来源引用的结构化答案。
切换嵌入提供程序、调整分块参数并配置搜索——所有操作均在运行时完成，无需重启。
git clone https://github.com/Destrayon/Connapse.git && cd Connapse && docker-compose up -d
# Open http://localhost:5001.NET 10 SDK (用于开发)
(可选) Ollama 用于本地嵌入
# Clone the repository
git clone https://github.com/Destrayon/Connapse.git
cd Connapse
# Set required auth environment variables (or use a .env file)
export CONNAPSE_ADMIN_EMAIL=admin@example.com
export CONNAPSE_ADMIN_PASSWORD=YourSecurePassword123!
export Identity__Jwt__Secret=$(openssl rand -base64 64)
# Start all services (PostgreSQL, MinIO, Web App)
docker-compose up -d
# Open http://localhost:5001 — log in with the admin credentials above首次运行将：
拉取 Docker 镜像（约 2-5 分钟）
初始化带有 pgvector 扩展的 PostgreSQL 并运行 EF Core 迁移
创建 MinIO 存储桶
播种管理员账户（来自环境变量）并启动 Web 应用程序
# Start infrastructure only (database + object storage)
docker-compose up -d postgres minio
# Run the web app locally
dotnet run --project src/Connapse.Web
# Run all tests
dotnet test
# Run just unit tests
dotnet test --filter "Category=Unit"安装 CLI（选择一种方式）：
# Option A: .NET Global Tool (requires .NET 10)
dotnet tool install -g Connapse.CLI
# Option B: Download native binary from GitHub Releases (no .NET required)
# https://github.com/Destrayon/Connapse/releases基本用法：
# Authenticate first
connapse auth login --url https://localhost:5001
# Create a container (project)
connapse container create my-project --description "My knowledge base"
# Upload files
connapse upload ./documents --container my-project
# Search
connapse search "your query" --container my-project
# Update to latest release (--pre to include alpha/pre-release builds)
connapse update
connapse update --preConnapse 包含一个模型上下文协议 (MCP) 服务器，用于与 Claude 和任何 MCP 客户端集成。
设置：通过 Web UI（设置 → 智能体 API 密钥）或 CLI (connapse auth agent-key create) 创建智能体 API 密钥，然后为你的客户端添加配置片段：
claude mcp add connapse --transport streamable-http http://localhost:5001/mcp --header "X-Agent-Api-Key: YOUR_API_KEY"添加到你的 claude_desktop_config.json：
{
"mcpServers": {
"connapse": {
"transport": "streamable-http",
"url": "http://localhost:5001/mcp",
"headers": {
"X-Agent-Api-Key": "YOUR_API_KEY"
}
}
}
}添加到你的 .vscode/settings.json (VS Code) 或 Cursor MCP 配置中：
{
"mcp": {
"servers": {
"connapse": {
"transport": "streamable-http",
"url": "http://localhost:5001/mcp",
"headers": {
"X-Agent-Api-Key": "${input:connapseApiKey}"
}
}
}
}
}VS Code 将在首次使用时提示输入 API 密钥。
MCP 服务器公开了 11 个工具：
工具 | 描述 |
| 创建一个用于组织文件的新容器 |
| 列出所有带有文档计数的容器 |
| 删除一个容器 |
| 获取容器统计信息（文档、分块、存储、嵌入） |
| 将单个文件上传到容器 |
| 在一次操作中上传最多 100 个文件 |
| 列出路径下的文件和文件夹 |
| 检索文档的完整解析文本内容 |
| 从容器中删除单个文件 |
| 在一次操作中删除最多 100 个文件 |
| 在容器内进行语义、关键词或混合搜索 |
完整参考：请参阅 docs/mcp-tools.md 获取参数表、返回格式、错误案例和使用示例。
写入保护：Amazon S3 和 Azure Blob 存储容器是只读的（从源同步）。文件系统容器遵循每个容器的权限标志。如果容器阻止写入，上传和删除工具将返回错误。
“创建一个名为 'project-research' 的容器，用于存放我的架构笔记”
“将我下载文件夹中的所有 PDF 上传到 project-research 容器”
“在我的 project-research 容器中搜索关于限流策略的信息”
“列出我 project-research 容器中 /notes/ 文件夹下的所有文件”
“获取 project-research 中 distributed-systems-notes.md 的全文”
“从 project-research 中删除 meeting-2026-03-14.md 并上传此更新版本”
“删除 project-research 中 /drafts/ 文件夹下的所有文件”
“我的 project-research 容器中有多少文档和分块？”
Connection refused on localhost:5001 — Docker 未运行或端口冲突。检查 docker compose ps 和 docker compose logs web。
401 Unauthorized / API 密钥无效 — 在“设置 > 智能体 API 密钥”中验证密钥。密钥仅在创建时显示一次。
工具未在 Claude 中显示 — 配置更改后重启你的 MCP 客户端。使用 curl http://localhost:5001/mcp 验证端点。
上传失败或超时 — 检查文件类型是否在允许列表中。最大文件大小取决于服务器配置。
搜索无结果 — 文档上传后需要时间进行嵌入。检查容器统计信息以查看嵌入进度。
Related MCP server: mnemostack
🗂️ 容器隔离知识 — 每个项目都有自己的向量索引、存储连接器和搜索配置。项目、团队或客户之间不会交叉污染。
🔍 混合搜索 — 向量相似度 + 关键词全文搜索，支持可配置的融合（凸组合、DBSF、AutoCut）。获取纯向量搜索无法找到的结果。
🧠 多提供程序 AI — 在运行时，按容器切换 Ollama、OpenAI、Azure OpenAI 和 Anthropic，用于嵌入和 LLM，无需重启。
🔌 索引现有存储 — 连接 MinIO、本地文件系统（实时文件监控）、Amazon S3 (IAM 认证) 或 Azure Blob 存储（托管身份）。你的文件保持原位。
🤖 4 种访问界面 — Web UI、REST API、CLI（原生二进制文件）和 MCP 服务器（为 Claude 提供 11 个工具）。专为人类、脚本和 AI 智能体打造。
🔐 企业级认证 — 多层 RBAC（Cookie + OAuth 2.1 + PAT + JWT），支持 AWS IAM Identity Center 和 Azure AD 身份链接。云权限是事实来源。
🐳 一键部署 — Docker Compose 包含 PostgreSQL + pgvector、MinIO 和可选的 Ollama。内置结构化审计日志和限流功能。
📄 多格式摄入：PDF、Office 文档、Markdown、纯文本 — 自动解析、分块和嵌入
⚡ 实时处理：通过 SignalR 进行后台摄入并实时更新进度
🎛️ 运行时配置：无需重启即可更改每个容器的分块策略、嵌入模型和搜索设置
☁️ 云身份链接：AWS IAM Identity Center (设备认证流程) + Azure AD (OAuth2+PKCE)，并强制执行 IAM 派生范围
👥 仅限邀请访问：管理员控制的用户注册，具有四种角色（管理员/编辑者/查看者/智能体）
🤖 智能体管理：专用的智能体实体，具有 API 密钥生命周期、范围权限和审计追踪
📋 审计日志：针对上传、删除、容器操作和认证事件的结构化审计追踪
📦 CLI 分发：原生自包含二进制文件（Windows/Linux/macOS）以及通过 NuGet 提供的 .NET 全局工具
🔄 跨模型搜索：项目进行中切换嵌入模型 — 自动为旧向量提供语义→混合回退
AI 智能体开发者：需要一个智能体既能查询又能构建的知识后端 — 上传研究资料、策划语料库，并通过 MCP 或 REST API 进行搜索
.NET / Azure 团队：需要一个符合现有技术栈和云身份的 RAG 平台
企业团队：需要具有适当 RBAC 和审计追踪的项目隔离知识库
厌倦了重复上传文件的人 — 将 Connapse 指向你现有的 Amazon S3/Azure Blob 存储/文件系统存储
本项目处于积极开发阶段 (v0.3.2)，即将达到生产就绪状态。
v0.3.x 增加了基于 IAM 访问控制的云连接器架构、多提供程序嵌入和 LLM 支持、云身份链接 (AWS SSO + Azure AD) 以及限流功能。
✅ 认证和授权 (v0.2.0)
✅ 基于角色的访问控制 (管理员/编辑者/查看者/智能体)
✅ 审计日志
✅ 云身份链接 — AWS IAM Identity Center + Azure AD OAuth2+PKCE (v0.3.0)
✅ IAM 派生范围强制执行 — 云权限是事实来源 (v0.3.0)
✅ 限流 — 内置 ASP.NET Core 中间件，具有针对用户和 IP 的策略 (v0.3.2)
⚠️ 在生产环境中设置强 Identity__Jwt__Secret — 请参阅 部署指南
请参阅 SECURITY.md 获取完整的安全策略。
┌──────────────────────────────────────────────────────────────────────┐
│ Access Surfaces │
│ Web UI (Blazor) │ REST API │ CLI │ MCP Server │
└─────────────┬────────────────────────────────────────────────────────┘
│
┌─────────────▼────────────────────────────────────────────────────────┐
│ Core Services Layer │
│ Document Store │ Vector Store │ Search │ Ingestion │
└─────────────┬────────────────────────────────────────────────────────┘
│
┌─────────────▼────────────────────────────────────────────────────────┐
│ Connectors Layer │
│ MinIO │ Filesystem │ Amazon S3 │ Azure Blob Storage │
└─────────────┬────────────────────────────────────────────────────────┘
│
┌─────────────▼────────────────────────────────────────────────────────┐
│ Infrastructure │
│ PostgreSQL+pgvector │ MinIO (S3) │ Ollama (optional) │
└──────────────────────────────────────────────────────────────────────┘[Upload] → [Parse] → [Chunk] → [Embed] → [Store] → [Searchable]
↓
[Metadata]
↓
[Document Store]目标：从上传到可搜索 < 30 秒。
关键技术：
数据库：PostgreSQL 17 + pgvector 用于向量嵌入
对象存储：托管存储抽象 — 默认为 MinIO (S3 兼容)，可按部署覆盖
后端：ASP.NET Core 10 最小 API
前端：Blazor Server (交互模式)
嵌入：Ollama (默认)、OpenAI、Azure OpenAI (可配置)
LLM：Ollama、OpenAI、Azure OpenAI、Anthropic (可配置)
搜索：混合向量 + 关键词，带有凸组合融合
连接器：托管存储 (默认 MinIO)、文件系统、Amazon S3、Azure Blob 存储
架构指南 - 系统设计和组件概述
API 参考 - REST API 端点和示例
连接器指南 - 连接器类型、配置和后台同步
AWS SSO 设置 - AWS IAM Identity Center 集成
Azure 身份设置 - Azure AD OAuth2+PKCE 集成
部署指南 - Docker 和生产环境设置
安全策略 - 安全限制和路线图
贡献指南 - 如何贡献
Connapse 处于 1.0 版本之前。主要设计工作在 Discussions 中跟踪。
✅ 文档摄入管道 (PDF, Office, Markdown, 文本)
✅ 混合搜索 (向量 + 关键词，带有凸组合融合)
✅ 带有文件夹的基于容器的文件浏览器
✅ Web UI, REST API, CLI, MCP 服务器
✅ 三层认证：Cookie + 个人访问
Delete up to 100 files in one call. Returns per-file success/failure results.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| fileIds | Yes | JSON array of file (document) IDs to delete, e.g. ["id1","id2"]. Max 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavioral details beyond the destructiveHint annotation, such as the batch limit and per-file result format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and limits, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description compensates by noting per-file results. Covers key constraints (limit, return format). Could mention error handling for missing files, but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes both parameters fully (100% coverage). The description does not add new semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), resource (files), and limits (up to 100, one call), distinguishing it from single-file deletion and bulk upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for deleting multiple files up to 100, but lacks explicit when-to-use vs alternatives or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload up to 100 files in one call. Each file is parsed, chunked, and embedded. Returns per-file results.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| files | Yes | JSON array of file objects. Each object: {"filename":"name.txt", "content":"...", "encoding":"text|base64", "folderPath":"/optional/"}. Max 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the processing pipeline (parse, chunk, embed) but lacks details on error handling for partial failures, file size limits, or supported formats. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Every sentence provides essential information: capacity, processing, and return type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should clarify return values. 'Returns per-file results' is vague; could specify status, errors, or IDs. Also missing constraints like file size, timeout, or authentication requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, both parameters are documented. The description adds 'Max 100' which reinforces the schema's 'max 100' constraint in files parameter description, but no new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Upload' with resource 'files', states the limit 'up to 100', and explains the processing pipeline ('parsed, chunked, and embedded'). It clearly distinguishes from sibling 'upload_file' which handles single files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies bulk usage via 'up to 100 files' but does not explicitly state when to use this over single upload or alternatives like 'search_knowledge'. No when-not or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new container for organizing documents. Use when setting up a new knowledge domain or project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Container name (lowercase alphanumeric and hyphens, 2-128 chars) | |
| description | No | Optional description for the container |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states creation purpose, lacking details on permissions, side effects, or duplicate handling. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences, front-loaded with action, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not mention return value (e.g., created container info). Adequate for simple tool but incomplete on expected response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for both parameters. Description repeats the same meaning, adding no extra value. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action (create), resource (container), and purpose (organizing documents). Distinguishes from sibling tools like container_delete or container_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when setting up a new knowledge domain or project', providing clear context. Does not mention exclusions or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a container. MinIO containers must be emptied first. Filesystem/S3/Azure files are not deleted — only the index is removed.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds important behavioral details: files are not deleted, only the index is removed, and MinIO containers must be emptied first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and followed by key constraints, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essential behavior, prerequisites, and what is not deleted, though it could mention irreversibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add additional meaning beyond the schema's parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a container, and differentiates from sibling tools like delete_file by clarifying that files are not deleted, only the index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies a prerequisite (MinIO containers must be emptied) and clarifies what is not affected, but does not explicitly compare to alternatives like bulk_delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all containers with document counts. Use to discover available knowledge bases before searching.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat these. It adds the return of document counts, but lacks details on pagination or performance. With annotations covering safety, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (12 words) that are front-loaded and contain no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the tool's purpose and usage context well. It mentions 'document counts,' giving insight into return data, but could be slightly more detailed on output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds no parameter info, which is appropriate. Baseline 4 for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all containers with document counts and specifies its use for discovering knowledge bases before searching. This differentiates it from sibling tools like container_stats or container_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use to discover available knowledge bases before searching,' providing clear context for when to use it. It lacks explicit exclusion guidance but is sufficient given the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get container statistics: document counts, chunk count, storage size, and embedding model info.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds value by specifying the exact statistics returned, providing context beyond what annotations offer. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and output details with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only tool with one parameter and no output schema, the description fully covers what the tool returns and its use case, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage for the single parameter (containerId) with a clear description. The tool description does not add additional semantic meaning for the parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get container statistics' and lists specific data (document counts, chunk count, storage size, embedding model info), making it distinct from siblings like container_list which only list container IDs or names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving statistics of a specific container but does not explicitly state when to use it over alternatives or provide exclusions. No guidance on prerequisites (e.g., container must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file and all its chunks and vectors. To update a file, delete it first then re-upload with upload_file.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| fileId | Yes | File (document) ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true. The description adds value by specifying that chunks and vectors are also deleted, giving a fuller scope of the operation's effects. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first clearly states the purpose, second provides a practical usage tip. No fluff, front-loaded, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with full schema coverage and an annotation, the description adequately covers the deletion scope and provides an update workflow hint. It could mention irreversibility or permissions, but these are implied by the destructive hint. Overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters (containerId and fileId) with descriptions, achieving 100% coverage. The description does not add extra semantic detail beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a file and all its chunks and vectors', which specifies the verb (delete) and resource (file and associated data). It also distinguishes from siblings like bulk_delete by implying single-file deletion via the fileId parameter, and provides additional context about updating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit guidance for updating: 'To update a file, delete it first then re-upload with upload_file.' However, it does not explicitly warn against using this tool for bulk deletions or when to prefer bulk_delete, though the parameterization hints at single-file usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a document's full text by ID or path. Returns extracted text for binary formats (PDF, DOCX, PPTX).
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| fileId | Yes | Document ID (UUID) or virtual path (e.g., '/docs/readme.md') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds that it returns extracted text for binary formats (PDF, DOCX, PPTX) beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences, no waste, clearly communicate purpose and key behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with 2 required parameters, description covers purpose, return value (full text, extraction for binaries). Lacks error handling or response format, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for both parameters. Description restates 'by ID or path' but adds no new semantic detail beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Retrieve' and resource 'document's full text', specifies query by ID or path, and mentions handling of binary formats. Distinguishes from siblings like list_files (metadata) and search_knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage context as a read-only retrieval tool, but no explicit when-to-use or alternatives (e.g., 'for metadata use list_files'). Clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and folders at a path within a container. Use to browse container contents before retrieving documents.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| path | No | Folder path to list (default: root '/') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the browsing context but does not disclose additional behavioral traits such as pagination or error handling, which would provide further transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences: one for the core function and one for usage guidance. Every word is necessary and no information is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with two parameters and no output schema, the description is fairly complete. It covers what the tool does and when to use it, though it could mention the return structure (e.g., list of file names) to be fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter details beyond what the schema already provides for containerId and path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' and specifies the resource 'files and folders at a path within a container'. It also provides context by stating its use case 'before retrieving documents', which distinguishes it from siblings like get_document, upload_file, and delete_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool to browse container contents before retrieving documents, giving clear context. However, it does not explicitly exclude other uses or mention alternatives beyond the implied contrast with get_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search a container using semantic, keyword, or hybrid mode. Returns ranked document chunks with scores. Use when answering questions from stored knowledge.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query text | |
| containerId | Yes | Container ID or name to search within | |
| mode | No | Search mode: Semantic (vector), Keyword (full-text), or Hybrid (both). Default: Hybrid | |
| topK | No | Number of results to return. Default: 10 | |
| path | No | Optional: Filter results to a folder subtree (e.g., '/docs/') | |
| minScore | No | Minimum similarity score floor (0.0-1.0). Defaults to 0.05. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the main behavioral traits are covered. The description adds 'Returns ranked document chunks with scores,' which gives some extra context but is not critical. No destructive behavior or auth needs are mentioned, but annotations suffice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence covering purpose and behavior, and the second giving usage guidance. Every sentence adds value, and there is no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage, the presence of annotations, and no output schema, the description is fairly complete. It covers purpose, usage, and return type. However, it could briefly mention that results are from the specified container, but that is implicit in the first sentence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description in the input schema. The tool description does not add any additional information about the parameters beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search a container') and specifies the modes (semantic, keyword, hybrid). It also mentions the return type ('ranked document chunks with scores'), making the tool's purpose distinct from siblings like container_list or get_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly suggests using the tool 'when answering questions from stored knowledge,' providing a clear use case. However, it does not mention when not to use it or compare to alternatives, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to be parsed, chunked, embedded, and made searchable. Provide either 'content' (base64) or 'textContent' (raw text), not both.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| content | No | Base64-encoded file content. For binary files (PDF, DOCX, images). Mutually exclusive with textContent. | |
| textContent | No | Raw text content for text-based files (Markdown, TXT, CSV, JSON, etc.). Mutually exclusive with content. | |
| fileName | No | Original file name with extension | |
| path | No | Destination folder path (e.g., '/docs/2026/') | |
| strategy | No | Chunking strategy: Semantic, FixedSize, or Recursive. Default: Semantic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It mentions the processing pipeline (parse, chunk, embed) and mutual exclusivity of content types, but does not disclose failure modes, idempotency, permissions, or response format. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The purpose is front-loaded, and essential usage hint is included. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (1 required), schema covers all, and no output schema, the description is fairly complete. It explains the overall goal and key constraint. However, it omits details on return value or confirmation. Still, it is adequate for an agent to understand and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reiterates the mutual exclusivity of content and textContent already in schema descriptions, adding minimal extra meaning. No new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Upload a file') and the resource, and describes the processing pipeline ('parsed, chunked, embedded, and made searchable'). This distinguishes it from sibling tools like bulk_upload (multiple files) and delete_file (deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a parameter usage guideline ('Provide either content or textContent, not both') but lacks explicit guidance on when to use this tool over siblings like bulk_upload or search_knowledge. No when-not-to-use or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.2bulk_deletebulk_uploadcontainer_createcontainer_deletecontainer_listcontainer_statsdelete_fileget_documentlist_filessearch_knowledgeupload_fileScored across 11 tools
Each tool targets a distinct operation: container management, file operations, bulk actions, and search. No two tools have overlapping purposes; even delete_file and bulk_delete are clearly scoped by single vs batch.
All tools follow a consistent verb_noun snake_case pattern (e.g., container_create, upload_file, search_knowledge). No mixed conventions or vague verbs.
11 tools is well-scoped for a knowledge management server, covering container CRUD, file operations, bulk operations, and search. No redundancy or missing essential operations.
Covers most lifecycle operations: container create/list/delete, file upload/get/list/delete, bulk upload/delete, and search. Missing container update and folder creation, but these are minor gaps that agents can work around.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.
Governed, auditable knowledge your team curates for its AI assistants, self-hostable
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
