infino-ai

Infino MCP 服务

这是一个适用于 Infino 的 MCP 服务，可让 AI Agent 通过任何兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor、VS Code 等），在对象存储中的数据上执行关键词、语义、混合和 SQL 检索，为 RAG、持久化 Agent 记忆以及对自有文件的搜索提供检索层。该服务已发布到 npm，包名为 @infino-ai/mcp-server，并列入官方 MCP Registry，条目为 io.github.infino-ai/mcp-server（并同步至 Smithery、Glama 和 PulseMCP 等目录）。

• 本地嵌入，无需密钥。 语义搜索使用本地模型对查询进行嵌入，嵌入过程不会让任何数据离开本机。
• 数据由 Agent 掌控。 所有工具（包括写入工具）始终可用。在 Infino Cloud 上，API 密钥的权限决定连接可以执行哪些操作；每个工具都带有 MCP 注释，客户端可以在执行破坏性调用前征求确认。
• 本地或托管。 可指定本地路径、自有存储桶（S3、Azure 或任何兼容 S3 的存储），或提供 API 密钥以连接托管的 Infino Cloud 端点。
• 索引是有效的 Parquet 文件。 表格以纯 Parquet 格式将数据及其搜索索引存储在存储中，可用 DuckDB 或 pyarrow 打开同一个文件。无需导出，也不会被锁定。

---

目录

• 要求
• 快速开始
• Claude Code 插件（一步安装）
• 客户端配置
  • Claude Code
  • Claude Desktop
  • Cursor
  • VS Code
  • 其他 MCP 客户端
• 配置
  • 环境变量
  • 存储后端
• 工具
• 安全与数据处理
• 检索工作原理
• 故障排除
• 本地开发
• 许可证

---

要求

• Node.js ≥ 20（服务以 Node 进程的形式通过 stdio 运行）。
• 兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor、VS Code 等）。
• Infino 可访问的数据——本地目录、环境中已有凭据的存储桶，或提供 API 密钥的托管 Infino Cloud 端点（参见存储后端）。
• 首次运行时，服务会下载本地嵌入模型（约 90 MB）并缓存；之后进行嵌入时无需联网。

---

快速开始

服务由 MCP 客户端通过 stdio 启动，正常使用时无需直接运行。每个客户端的配置格式相同：命令为 npx -y @infino-ai/mcp-server，配置通过环境变量提供。将 INFINO_MCP_URI 设为要提供服务的数据位置——本地路径或存储桶 URI。若未设置，服务会使用每位用户专属的持久目录（~/.infino/mcp），以便数据在重启后继续保留；如需提供现有数据，请将 INFINO_MCP_URI 指向自有路径或存储桶。

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "/Users/me/.infino/memory"
  }
}

若要改为提供托管的 Infino Cloud 数据库，请将 INFINO_MCP_URI 指向 https://<host>/<database> 端点，并提供 API 密钥。其他配置 完全相同：

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "https://api.platform.infino.ws/my-database",
    "INFINO_API_KEY": "inf_…"
  }
}

下文将说明各客户端要求放置此配置块的确切位置。

---

Claude Code 插件（一步安装）

对于 Claude Code，此仓库也是一个插件市场。安装插件后，只需一步即可配置 MCP 服务、使用指南技能和 /infino-search 命令，无需编辑 JSON。在 Claude Code 中：

/plugin marketplace add infino-ai/infino-mcp
/plugin install infino@infino-ai

启用时，系统会提示你输入Infino 数据 URI（INFINO_MCP_URI），如果使用 Infino Cloud，还需输入API 密钥。就这么简单：随后即可使用 infino_* 工具、using-infino 技能和 /infino-search <query>。（其他客户端：请使用下方的客户端设置配置。）

---

客户端设置

Claude Code

使用 CLI 添加服务。使用 --scope user 可在每个项目中使用，使用 --scope project 可将其提交到仓库（写入共享的 .mcp.json）；默认范围为 local（仅限此项目）。

claude mcp add infino \
  --scope user \
  -e INFINO_MCP_URI=/Users/me/.infino/memory \
  -- npx -y @infino-ai/mcp-server

使用重复的 -e 标志添加更多选项，例如 -e INFINO_MCP_VALIDATE=true。使用以下命令验证：

claude mcp list
claude mcp get infino

Claude Desktop

编辑配置文件（若文件不存在，则创建），然后完全重启 Claude Desktop。

OS	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "infino": {
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

Cursor

将服务添加到 ~/.cursor/mcp.json（适用于所有项目）或 <project>/.cursor/mcp.json（仅限此项目），然后重新加载。格式与 Claude Desktop 相同：

{
  "mcpServers": {
    "infino": {
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

VS Code

VS Code（1.102+）从工作区中的 .vscode/mcp.json（或通过命令面板 → MCP: Open User Configuration 打开用户 mcp.json）读取 MCP 服务。请注意，顶层键为 servers，每个条目都声明 "type": "stdio"：

{
  "servers": {
    "infino": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

其他 MCP 客户端

任何支持通过 stdio 使用 MCP 的客户端都可以使用。配置客户端以启动：

command: npx
args:    -y @infino-ai/mcp-server
env:     INFINO_MCP_URI=<path-or-bucket-uri>   (plus any options below)

日志写入 stderr，因此不会破坏 stdout 上的 JSON-RPC 流 — 调试时，请将客户端的日志捕获指向此处。

---

配置

所有配置都通过环境变量完成 — 无需管理配置文件或命令行标志。

环境变量

变量	必填	默认值	说明
INFINO_MCP_URI	否	~/.infino/mcp（持久化）	要提供服务的数据：本地路径（/Users/me/.infino/memory）、存储桶 URI（s3://…、az://…）或托管端点（https://<host>/<database>，Infino Cloud）。如果未设置，则使用持久的用户目录（~/.infino/mcp），以便数据在重启后保留；只有在无法创建该目录时，才会回退到临时的进程内目录（memory://）。
INFINO_API_KEY	使用托管 URI 时	—	托管 https:// 端点的 API 密钥（inf_…）。当 INFINO_MCP_URI 是 https:// URI 时必填；本地连接和对象存储连接会忽略此项。
INFINO_MCP_EMBED_PROVIDER	否	local	嵌入提供方：local（Hugging Face transformers.js，无需密钥，任何数据都不会离开本机）或 openai（任何兼容 OpenAI 的 /embeddings 端点——OpenAI、Azure OpenAI 的 /openai/v1 接口，或兼容服务）。如果设置了 INFINO_MCP_EMBED_BASE_URL，则会推断为 openai。
INFINO_MCP_EMBED_BASE_URL	使用 openai 时	—	兼容 OpenAI 的嵌入 API 基础 URL，例如 https://api.openai.com/v1 或 https://<resource>.openai.azure.com/openai/v1。服务会向 <base>/embeddings 发送 POST 请求。
INFINO_MCP_EMBED_API_KEY	否	—	openai 提供方的 API 密钥。密钥会同时通过 Authorization: Bearer 和 api-key 发送，因此同一个值可用于 OpenAI 和 Azure OpenAI。对于无需身份验证或使用环境身份的端点，可省略此项。
INFINO_MCP_EMBED_MODEL	否	Xenova/all-MiniLM-L6-v2（local）· text-embedding-3-small（openai）	嵌入模型。对于 local，这是 Hugging Face 特征提取模型；对于 openai，这是模型或部署名称。必须与生成表中已存储向量的模型一致，因此也必须与向量索引维度一致（例如，text-embedding-3-small 为 1536 维；默认本地模型为 384 维）。
INFINO_MCP_VALIDATE	否	关闭	设置为 1/true/yes 时，会在启动时探测对象存储，使错误凭据或无法访问的存储桶在此时就报错，而不是等到首次搜索时才报错。

云凭据从标准提供方环境变量中读取——服务会将它们映射到存储配置，不会引入自己的凭据变量。完全省略这些变量即可使用环境身份（IAM 实例角色或 Azure 托管身份）。

提供使用 OpenAI / Azure OpenAI 嵌入的目录。 如果表格使用托管嵌入模型而非本地默认模型进行向量化，请将服务指向同一模型，以确保查询向量与文档向量一致：

"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "INFINO_MCP_EMBED_PROVIDER": "openai",
  "INFINO_MCP_EMBED_BASE_URL": "https://my-resource.openai.azure.com/openai/v1",
  "INFINO_MCP_EMBED_API_KEY": "…",
  "INFINO_MCP_EMBED_MODEL": "text-embedding-3-small"
}

模型必须与生成已存储向量的模型一致——不匹配会导致相似度结果毫无意义或出现维度错误。关键词搜索和 SQL 搜索不受嵌入模型影响。

后端	凭据
AWS S3	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY（如果使用，还包括 AWS_SESSION_TOKEN、AWS_REGION）
兼容 S3 的存储（R2/MinIO/B2）	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_ENDPOINT_URL
Azure Blob	AZURE_STORAGE_ACCOUNT、AZURE_STORAGE_KEY
Infino Cloud（托管）	INFINO_API_KEY——无需对象存储凭据（存储由平台管理）

存储后端

// Local directory
"env": { "INFINO_MCP_URI": "/Users/me/.infino/memory" }

// AWS S3 — ambient AWS_* credentials, default endpoint
"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "AWS_ACCESS_KEY_ID": "…",
  "AWS_SECRET_ACCESS_KEY": "…"
}

// S3-compatible (Cloudflare R2 / MinIO / Backblaze B2) — custom endpoint
"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "AWS_ENDPOINT_URL": "https://<account>.r2.cloudflarestorage.com",
  "AWS_ACCESS_KEY_ID": "…",
  "AWS_SECRET_ACCESS_KEY": "…"
}

// Azure Blob
"env": {
  "INFINO_MCP_URI": "az://my-container/infino",
  "AZURE_STORAGE_ACCOUNT": "…",
  "AZURE_STORAGE_KEY": "…"
}

// Infino Cloud (hosted) — the database is the last path segment
"env": {
  "INFINO_MCP_URI": "https://api.platform.infino.ws/my-database",
  "INFINO_API_KEY": "inf_…"
}

使用托管连接时，搜索、SQL 和写入工具的行为与本地使用时完全相同——唯一的区别是数据存储的位置。压缩和垃圾回收由服务端处理，因此不会作为客户端操作提供。请注意，语义搜索和混合搜索仍会在此服务中本地嵌入查询，因此 INFINO_MCP_EMBED_MODEL 必须与生成托管表中已存储向量的模型一致（请参阅上文关于 OpenAI / Azure OpenAI 的说明）——尤其是在由其他人导入数据时，这一点很重要。

---

工具

工具	参数	功能
infino_semantic_search	table、query、k、column?、vectorColumn?、columns?、filter?	按含义查找段落——使用本地模型对查询进行嵌入（无需密钥），并按向量相似度排序。可处理释义和同义词。score 表示距离（越小越接近）。可选的 filter（{column, query, mode?}）会先将排序范围限制为关键字列匹配的行（下推预筛选）。可选的 columns 用于选择每条命中结果返回的字段（例如用于引用的路径和行范围）；默认返回文本列，并始终包含 _id 和 score。
infino_keyword_search	table、query、k、column?、mode?、columns?	BM25 全文搜索——适用于精确术语、标识符、错误代码和产品名称。score 表示相关性（越高越好）。mode 为 or（默认）或 and。
infino_hybrid_search	table、query、k、column?、vectorColumn?、mode?、columns?	在一次排序中融合关键字搜索与语义搜索——将文本列上的 BM25 与向量相似度结合，因此同时匹配字面术语和含义的行排名最高。score 表示融合排名（越高越好）。
infino_token_match	table、query、column?、mode?、limit?	不排序的关键字筛选——返回文本列包含指定词元的行集合。需要匹配结果而非相关性排序时使用。
infino_exact_match	table、value、column?、limit?	对索引列（标签、状态、ID 字符串）进行不排序的精确相等筛选。
infino_count	table、query、column?、mode?	统计匹配关键字查询的行数，无需获取这些行——快速统计文本列中的匹配项。若要获取匹配行，请使用 infino_keyword_search 或 infino_token_match。
infino_sql	query、embed?	用于计数、筛选、联接和聚合的 SQL。引擎的搜索表函数可在其中调用；{{name}} 占位符会替换为 embed[name] 的向量。支持任意单条语句，包括 DDL/DML。
infino_list_tables	—	列出已连接目录中的表。
infino_describe_table	table	获取表的列名和类型。
infino_create_database	—	在连接指定的位置创建数据库（Infino Cloud）；在本地执行时则为空操作并返回成功。此操作幂等。
infino_create_table	table、columns、fts?、vector?	根据 {column: type} 描述符创建表。在 fts 指定的列上创建全文索引（默认：所有 large_utf8 列）。vector: true 会添加一个大小与服务端嵌入器相匹配的 embedding 列，并创建余弦索引。
infino_drop_table	table、purge?	删除表，并默认删除其存储对象；purge: false 则仅注销表名。
infino_add_documents	table、documents	追加行（一次调用即一次提交）。没有向量的行会从文本列生成嵌入，并一次性批量处理；结果会报告 appended 和 embedded。使用非列名的键会导致错误。
infino_update_documents	table、predicate、documents	用新文档按 1:1 替换匹配 SQL 谓词的行（缺失的向量会生成嵌入）。仅适用于持久化存储。
infino_delete_documents	table、predicate	删除匹配 SQL 谓词的行。仅适用于持久化存储。
搜索命中会返回完整列值——columns 参数是直接传给引擎（嵌入式或托管式）的投影，因此表中的任意列都会随每条命中一起返回：["id"] 可在 k 较大时获得精简的命中结果，["id", "text"] 可在返回 id 的同时附带完整文本以供引用，也可以返回元数据列用于筛选。默认投影文本列，_id 和 score 始终包含在内，并且绝不会截断任何内容；若要缩小结果，请投影更少的列或使用更小的 k。每个搜索响应还会携带 score_kind，说明其 score 是距离（语义搜索：越低越接近）还是相关性（关键词和混合搜索：越高越好）。

对于普通检索，优先使用专用搜索工具，它们会为你完成嵌入和投影。infino_sql 用于筛选、联接和聚合，包括对搜索表值函数结果进行操作，因此一条查询就能同时完成排序和聚合。

写入数据

Agent 遵循的写入流程，每一步调用一次工具并提交一次：

1. 如果托管数据库返回 404，则调用 infino_create_database。
2. 调用 infino_create_table，使用 utf8 键列、large_utf8 文本列，并为语义搜索设置 vector: true。服务端会根据其嵌入器确定向量列的大小；Agent 无需输入维度。保留返回结果：其中的 indexes 字段是唯一记录哪些列已建立索引的地方。
3. 调用 infino_add_documents，每次写入数十行，并始终包含键。缺失的向量会批量嵌入。
4. 若要替换行，请按键谓词调用 infino_delete_documents，然后再次添加。若要删除行，请先用 infino_count 检查谓词。

一次工具调用可携带数十个文档。对于整个语料库，请使用 infino CLI（infino ingest 可通过相同 URI 导入 Parquet 或 NDJSON）或 SDK。与引擎一样，CLI 要求自行提供向量，因此请在行中包含 embedding 列，或加载文本并按关键词搜索。

服务端没有写入权限门控机制，已弃用的 INFINO_MCP_ENABLE_WRITES 变量也会被忽略（若设置了该变量，服务会在 stderr 中说明）。在 Infino Cloud 上，API 密钥的权限决定连接可执行的操作：只读密钥的所有写入都会被拒绝，工具结果会提示创建具有写入权限的密钥。在本地，请确保服务仅指向 Agent 可以修改的数据。

---

安全与数据处理

此服务在本地运行，与客户端位于同一设备上，数据和凭据均保存在用户的设备上。

• 本地执行，不监听入站连接。 它作为 MCP 客户端的子进程通过 stdio 运行，不会打开网络监听器。在默认的本地／存储桶模式下，它不会联系任何远程服务。如果 INFINO_MCP_URI 是托管的 https:// 端点，它会向该端点发起 出站 TLS 调用，以处理搜索、SQL 和（如果启用）写入操作——这些请求中的数据会到达你配置的托管服务，仅此而已。
• 默认情况下不会发送数据用于生成嵌入。 使用默认提供方时，查询和文档嵌入由本地模型完成，因此文本不会发送到第三方嵌入 API，也无需配置或担心泄露嵌入 API 密钥。在托管模式下，只有生成的向量会到达 Infino Cloud 端点，文本不会。如果你配置了兼容 OpenAI 的提供方，待嵌入的文本会发送到你指定的端点。
• 凭据保留在环境中。 存储凭据（AWS_*／AZURE_*）和托管 API 密钥（INFINO_API_KEY）从环境变量中读取，仅用于访问你配置的存储或端点。它们绝不会被记录到日志中，也不会在工具输出中返回。
• 写入权限由服务外部决定。 Agent 始终可以使用完整的工具集，包括写入工具。在 Infino Cloud 上，API 密钥的权限会限制连接可执行的操作（只读密钥的所有写入都会被拒绝）。在本地，只将 Agent 可修改的数据指向该服务。每个工具都带有 MCP 注释（readOnlyHint、destructiveHint），因此客户端可以按自身规则请求确认。
• 遵循最小权限原则。 将 INFINO_MCP_URI 指向任务所需的最小数据集，并提供权限仅限于该存储桶／前缀的存储凭据。

---

检索的工作原理

语义搜索使用 Hugging Face transformers.js 在本地生成嵌入（默认使用 all-MiniLM-L6-v2，维度为 384；可通过 INFINO_MCP_EMBED_MODEL 覆盖）。服务使用同一模型为导入的文档（通过 infino_add_documents）和你的查询生成嵌入，使它们位于相同的向量空间中。

如果更改 INFINO_MCP_EMBED_MODEL，表的向量索引必须与新模型的维度匹配——不同模型生成的嵌入不可比较，维度不匹配会导致搜索失败。

---

故障排除

症状	可能的原因／解决方法
客户端未显示 Infino 工具	服务未启动——检查客户端的 MCP 日志（stderr）。确认 npx 位于 PATH 中，并且已设置 INFINO_MCP_URI。编辑配置后，请完全重启客户端。
INFINO_MCP_URI is required	环境变量未传递到子进程。在图形界面客户端中，环境变量必须放在服务的 env 块中（进程不会继承你的 shell 环境）。
写入提示密钥“was rejected or lacks write capability”	在 Infino Cloud 上，API 密钥为只读权限（HTTP 403）或密钥有误。创建具有写入权限的密钥，并使用该密钥重启服务。
写入提示“another writer won the commit race”	两个写入方同时操作同一张表，且此次调用未能提交。请重新发起调用。
首次查询速度较慢	需要一次性下载嵌入模型（约 90 MB）。后续运行会使用缓存。
访问托管的 https:// URI 时出现身份验证错误	INFINO_API_KEY 缺失、有误，或无权访问该数据库。确认密钥（inf_…）正确，并确认 URI 的最后一个路径段是你有权访问的数据库。
语义搜索出现维度／向量错误	表的向量索引与嵌入模型的维度不匹配。请重新导入数据，或将 INFINO_MCP_EMBED_MODEL 设为创建索引时使用的模型。

---

本地开发

服务器依赖已发布的 @infino-ai/infino Node 绑定，它与其他依赖一样通过公共 npm 解析。

npm install
npm run build
INFINO_MCP_URI=/path/to/data node dist/index.js   # runs on stdio

将客户端配置为通过 stdio 连接到 node /absolute/path/dist/index.js，以试用本地构建；也可以使用 MCP Inspector：

npx @modelcontextprotocol/inspector node dist/index.js

---

许可证

Apache-2.0