Weaviate Ts

Weaviate MCP 服务器（TypeScript）

一个用于Weaviate向量数据库的模型上下文协议（MCP）服务器，采用TypeScript实现。该服务器提供了与MCP兼容的工具，用于查询和与Weaviate集合进行交互。

特点/功能

• 查询工具使用混合搜索查询Weaviate集合
• 文本生成工具使用Weaviate的生成式搜索功能生成文本
• 资源访问访问集合模式和元数据
• 多种运输方式支持stdio和HTTP传输
• 可配置日志记录灵活的日志记录，支持多种输出选项
• Docker 支持已准备好进行容器化部署

安装

先决条件

• Node.js 18.0.0 或更高版本
• npm 或 yarn
• 访问一个Weaviate实例

安装依赖项

npm install

配置

配置可以通过环境变量或命令行参数来提供。

环境变量

创建一个 .env 基于文件的 .env.example：

cp .env.example .env

可用的环境变量：

• WEAVIATE_HOST - Weaviate 主机（默认： host.docker.internal:8080）
• WEAVIATE_SCHEME - 连接方案（默认： http）
• MCP_TRANSPORT - 传输协议： stdio 或者 http （默认： stdio)
• MCP_HTTP_PORT - 使用HTTP传输时的HTTP端口（默认： 3000)
• MCP_HTTP_HOST - 使用HTTP传输时的HTTP主机（默认： 127.0.0.1）
• MCP_LOG_LEVEL - 日志级别： debug， info， warn， error （默认： info)
• MCP_LOG_OUTPUT - 日志输出： stderr， file， both （默认： stderr)
• MCP_READ_ONLY - 启用只读模式（默认： false）
• MCP_DISABLED_TOOLS - 以逗号分隔的禁用工具列表
• MCP_DEFAULT_COLLECTION - 默认集合名称（默认： DefaultCollection)

命令行参数

npm run dev -- --weaviate-host localhost:8080 --transport stdio --log-level debug

可用参数：

• --weaviate-host - Weaviate 主机
• --weaviate-scheme - Weaviate 方案（http/https）
• --transport - 传输协议（stdio/http）
• --http-port - HTTP端口
• --http-host - HTTP 主机
• --log-level - 日志级别
• --log-output - 日志输出
• --read-only - 启用只读模式
• --default-collection - 默认集合名称

使用方法

开发模式

# Start in development mode with auto-restart
npm run dev

# Start with debug logging
npm run dev -- --log-level debug --log-output both

# Start with HTTP transport
npm run dev -- --transport http

生产模式

# Build the project
npm run build

# Start the built application
npm start

使用 Make（工具）

# Install dependencies
make install

# Development mode
make dev

# Production build and start
make build
make start

# Debug mode
make dev-debug

# HTTP transport mode
make dev-http

工具

Weaviate查询

使用混合搜索从 Weaviate 集合中查询对象。

参数：

• query (字符串，必填) - 搜索查询
• collection (字符串，必填) - 目标集合名称
• targetProperties (数组，必需) - 要返回的属性
• limit (数字，可选) - 最大结果数（默认：3）

示例：

{
  "query": "artificial intelligence",
  "collection": "Articles",
  "targetProperties": ["title", "content", "author"],
  "limit": 5
}

Weaviate生成文本

使用 Weaviate 的生成式搜索功能生成文本。

参数：

• prompt (字符串，必填) - 用于生成的文本提示
• collection （字符串，必填）- 目标集合名称
• maxTokens （数字，可选）- 要生成的最大标记数（默认：100）

示例：

{
  "prompt": "Summarize the main points about AI",
  "collection": "Articles",
  "maxTokens": 200
}

资源

模式资源

通过类似以下的URI访问集合模式信息：

• weaviate://schema/{collection} - 特定集合的模式

Docker

构建Docker镜像

make docker-build

使用 Docker 运行

# Run with stdio transport
make docker-run

# Run with HTTP transport
make docker-run-http

手动 Docker 命令

# Build
docker build -t mcp-server-weaviate-ts .

# Run with stdio transport
docker run --rm -it mcp-server-weaviate-ts

# Run with HTTP transport
docker run --rm -it -p 3000:3000 mcp-server-weaviate-ts node dist/main.js --transport http

发展

代码质量

# Lint code
npm run lint

# Format code
npm run format

项目结构

src/
├── main.ts           # Main entry point
├── config.ts         # Configuration management
├── logger.ts         # Logging utilities
├── weaviate.ts       # Weaviate client wrapper
└── mcp.ts           # MCP server implementation

运输方式

stdio（推荐）

stdio 传输是 MCP 通信的主要方式：

npm run dev -- --transport stdio

HTTP（实验性）

HTTP传输可用，但可能需要额外的设置：

npm run dev -- --transport http --http-port 3000

记录日志

日志可以输出到：

• stderr - 标准错误流
• file - 日志文件已录入 logs/mcp-server.log
• both - 同时输出到 stderr 和文件

日志级别： debug， info， warn， error

故障排除

常见问题

1. 模块未找到错误跑 npm install 安装依赖项
2. Weaviate连接错误检查 WEAVIATE_HOST 并且 WEAVIATE_SCHEME 设置
3. 权限错误确保 logs/ 目录可写

调试模式

启用调试日志以查看详细信息：

npm run dev -- --log-level debug --log-output both

从Go版本迁移

这个TypeScript版本提供了与原始Go实现相同的功能：

• 所有工具和资源均得到保留
• 配置选项保持不变
• 运输方式相兼容
• Docker 部署的工作原理类似

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。