向量搜索服务器

MCP 向量服务器

注：这是一个私有项目，仅限内部使用。不涉及公共部署、拉取请求（PRs）以及持续集成/持续交付（CI/CD）。

一个可投入生产的模型上下文协议（MCP）服务器，使人工智能助手（如ChatGPT）能够对本地项目文档和代码库执行语义搜索。该服务器可接收来自 sandbox/将文本块和嵌入向量存储在PostgreSQL中，使用 pgvector 扩展功能，并提供MCP工具以实现智能知识检索。

目的

• 本地知识管理通过嵌入带有结构化元数据标签的本地文件，使项目上下文与开发紧密相连 [persona:dev] 或者 [project:example1]。
• 语义搜索利用OpenAI嵌入技术和向量相似度搜索，使AI助手能够通过自然语言查询文档和代码。
• 多租户架构使用专用的PostgreSQL数据库隔离项目mcp_vector_<project>)，确保数据隔离和可扩展的性能。
• MCP协议通过模型上下文协议（Model Context Protocol）提供标准化工具，使服务器与ChatGPT及其他符合MCP标准的客户端兼容。

特点/功能

当前版本（v0.1.0）

✅ MCP 服务器 (TypeScript + @modelcontextprotocol/sdk)

• 通过Cloudflare隧道进行远程访问的HTTP/SSE传输
• 用于本地开发的stdio传输
• 六款可投入生产的工具： db.list， search， fetch， read， write， ingest.changed， sandbox.read
• 两种资源： corpus://info， status://health

✅ 向量存储 （PostgreSQL 16+ 版本，搭配 pgvector 扩展）

• 按项目划分的数据库多租户（mcp_vector_example1等
• IVFFlat向量索引用于快速近似最近邻搜索
• 在JSONB元数据上使用GIN索引以实现高效过滤
• 带优雅关闭功能的连接池

✅（勾选标记，表示正确、确认或完成） 摄入管道（或摄入流程）

• 多粒度分块：文档级、递归式（约700个标记）、代码感知
• 从括号标签中提取元数据： [persona:dev]， [project:example1]
• OpenAI嵌入式API集成text-embedding-3-small，1536 维度)
• 增量更新：更新已更改的文件，删除已删除的文件

✅ 测试与质量

• 290项测试（270项单元测试+20项集成测试）
• 80.54%的语句覆盖率，83.55%的函数覆盖率
• 使用VectorStoreError进行全面的错误处理
• <5%的代码重复率（已通过jscpd验证）

先决条件

验证版本：

node --version    # v20.x.x
npm --version     # 10.x.x
psql --version    # PostgreSQL 16.x

快速入门

1. 克隆并安装

git clone https://github.com/your-org/mcp-vector-server.git
cd mcp-vector-server
npm ci

2. 启动 PostgreSQL

选项B：本地安装（此设置推荐）

brew services start postgresql@16  # macOS
# or
sudo systemctl start postgresql     # Linux

可选（Docker Compose）：如果您更喜欢使用容器，您可以启动在（某处）定义的Postgres服务 docker-compose.yml。

docker compose up -d postgres

3. 配置环境

创造 .env 文件：

# Database
DATABASE_URL=postgres://mcp:mcp@127.0.0.1:5432/mcp_vector_default

# OpenAI
OPENAI_API_KEY=sk-...your-api-key...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Server (optional)
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3333
MCP_HTTP_PATH=/mcp

4. 初始化数据库

# Run migrations
npm run db:migrate

# Create project databases
npm run seed:projects

5. 输入样本数据

# Ingest all projects from sandbox/
npm run ingest

# Or ingest specific project
npm run ingest -- --root-dir ./sandbox/example1

6. 启动服务器

# Development mode (auto-restart on changes)
npm run dev

# Production mode (compiled)
npm run build
npm start

预期输出：

MCP Vector Server starting...
✓ Database connection verified
✓ OpenAI API key configured
✓ Loaded 2 projects: example1, example2
Server listening on http://127.0.0.1:3333/mcp

7. 测试服务器

# List available databases
npm run tool:run -- db.list

# Run a search query
npm run tool:run -- search --query "authentication setup" --databaseId example1

# Read a file directly (sandbox)
npm run tool:run -- sandbox.read --path "docs/README.md" --databaseId example1

# Create or modify repo files safely (non-sandbox)
npm run tool:run -- read path=src/server/createMcpServer.ts
npm run tool:run -- write path=docs/new-notes.md mode=create content="# Notes\nHello!\n"
# Append via patch
npm run tool:run -- write path=docs/new-notes.md mode=patch patch='{"type":"append","data":"More\n"}'

# Incremental ingestion of changed files
# CLI
npm run ingest:changed -- --database mcp_vector_example1 --root-dir ../example1 --since main
# Tool via CLI helper
npm run tool:run -- ingest.changed databaseId=example1 since=main
# Read a repo file (non-sandbox)
npm run tool:run -- read path=src/server/createMcpServer.ts

可用脚本

项目结构

mcp-vector-server/
├── server.ts                     # HTTP server entry point
├── src/
│   ├── config/                   # Configuration (constants, defaults)
│   ├── db/                       # Database layer
│   │   ├── pool.ts              # Connection pooling
│   │   ├── schema.ts            # Drizzle ORM schema
│   │   ├── embeddingsRepository.ts  # Data access layer
│   │   └── projectRegistry.ts   # Multi-tenant project config
│   ├── ingestion/               # Ingestion pipeline
│   │   ├── walker.ts            # File discovery
│   │   ├── chunker.ts           # Text chunking
│   │   ├── embedder.ts          # OpenAI embedding generation
│   │   ├── fileProcessor.ts     # Content reading, tag extraction
│   │   ├── metadata.ts          # Metadata parsing
│   │   ├── pathResolver.ts      # Path normalization
│   │   ├── ingest.ts            # Orchestration
│   │   └── runIngestion.ts      # CLI entry point
│   ├── server/                  # MCP server implementation
│   │   ├── createMcpServer.ts   # Server initialization
│   │   ├── configHelpers.ts     # Config parsing
│   │   ├── httpHelpers.ts       # HTTP utilities
│   │   ├── jsonRpcHelpers.ts    # JSON-RPC logging
│   │   ├── schemas.ts           # Zod validation
│   │   ├── sanitizers.ts        # Input sanitization
│   │   ├── embeddingHelpers.ts  # OpenAI client wrappers
│   │   ├── tools/               # MCP tool implementations
│   │   │   ├── dbListTool.ts
│   │   │   ├── searchTool.ts
│   │   │   ├── fetchTool.ts
│   │   │   └── sandboxReadTool.ts
│   │   └── resources/           # MCP resource implementations
│   │       ├── corpusResource.ts
│   │       └── statusResource.ts
│   ├── types/                   # Shared TypeScript types
│   └── testUtils/               # Test utilities and mocks
├── scripts/                     # Operational scripts
│   ├── seedProjects.ts
│   ├── runMigrations.ts
│   ├── runTool.ts
│   ├── startStack.ts
│   └── resetStack.ts
├── docs/                        # Documentation
│   ├── architecture.md          # System architecture
│   ├── contributing.md          # Contribution guide
│   ├── testing.md              # Testing guidelines
│   ├── error-handling.md       # Error patterns
│   └── code-smell-analysis.md  # Code quality report
├── sandbox/                     # Project files for ingestion
│   ├── example1/
│   └── example2/
├── cloudflared/                 # Cloudflare tunnel config
│   ├── config.mcp.yml
│   └── credentials/
└── db/                         # Database initialization
    └── init/
        └── 001-create-extension.sql

MCP 工具

db.list

列出可用的项目数据库。

输入： 无

输出：

{
  "databases": [
    {
      "id": "example1",
      "database_name": "mcp_vector_example1",
      "description": "Example project",
      "file_count": 42,
      "root_path": "/path/to/sandbox/example1"
    }
  ]
}

search

跨项目嵌入的语义向量搜索。

输入：

{
  "query": "How do I configure authentication?",
  "databaseId": "example1",
  "top_k": 10, // Optional, default 10, max 50
  "persona": "dev", // Optional filter
  "project": "example1" // Optional filter
}

输出：

{
  "results": [
    {
      "file_path": "docs/authentication.md",
      "chunk_text": "Authentication is configured via...",
      "score": 0.87,
      "metadata": {
        "persona": ["dev", "ops"],
        "project": ["example1"],
        "granularity": "recursive"
      }
    }
  ]
}

fetch

通过块ID检索完整块内容。

输入：

{
  "chunkId": "docs/auth.md::0::recursive",
  "databaseId": "example1"
}

输出：

{
  "chunk_id": "docs/auth.md::0::recursive",
  "file_path": "docs/auth.md",
  "chunk_text": "# Authentication\n\n...",
  "metadata": {...}
}

sandbox.read

直接从项目沙盒读取文件系统。

输入：

{
  "path": "docs/README.md",
  "databaseId": "example1"
}

输出：

{
  "content": "# Project Documentation\n\n...",
  "size_bytes": 1024
}

安全：

• 路径遍历防护（../ 被阻止）
• 仅在项目根目录中进行沙盒化
• 10MB的大小限制

MCP Resources（公司名）可译为“MCP资源公司”

corpus://info

项目元数据和统计信息。

输出：

{
  "projects": [
    {
      "id": "example1",
      "name": "Example Project",
      "root_path": "/sandbox/example1",
      "file_count": 42,
      "total_chunks": 387
    }
  ]
}

status://health

服务器健康状况与配置。

输出：

{
  "status": "healthy",
  "server_version": "0.1.0",
  "database_connected": true,
  "openai_configured": true,
  "projects_loaded": 2
}

部署

本地开发

# Start PostgreSQL
docker-compose up -d postgres

# Start server
npm run dev

# Server listens on http://127.0.0.1:3333/mcp

生产（使用Cloudflare Tunnel）

如果您希望托管的ChatGPT访问您的本地MCP服务器，则此步骤为必选。若仅用于本地使用，则此步骤为可选。

1. 设置隧道凭据：

# Login to Cloudflare
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create mcp-vector

# Copy credentials to project
cp ~/.cloudflared/<tunnel-id>.json cloudflared/credentials/mcp-vector.json
cp ~/.cloudflared/cert.pem cloudflared/cert.pem

2. 配置隧道：

编辑 cloudflared/config.mcp.yml：

tunnel: <your-tunnel-id>
credentials-file: ./credentials/mcp-vector.json

ingress:
  - hostname: mcp-vector.your-domain.com
    service: http://host.docker.internal:3333
  - service: http_status:404

3. 启动服务器+隧道：

# Start PostgreSQL
docker-compose up -d postgres

# Start MCP server
npm start

# Start tunnel (in separate terminal)
npm run stack:start:follow

4. 测试远程访问：

curl https://mcp-vector.your-domain.com/mcp \
  -X OPTIONS \
  -H "Accept: application/json"

配置参考

环境变量

要求：

可选：

注：默认基础路径 /mcp 与……相匹配 normalizePath HTTP服务器默认使用的（见 src/server/configHelpers.ts）。

数据库配置

服务器使用一个 按项目划分的数据库 多租户模型：

PostgreSQL Instance
├── mcp_vector_default     # Default database (from DATABASE_URL)
├── mcp_vector_example1    # Project database (auto-created)
└── mcp_vector_example2    # Project database (auto-created)

每个项目数据库包含：

• embeddings 带有向量列的表格
• 向量相似度的IVFFlat索引
• 用于元数据过滤的GIN索引

分块策略

摄入管道使用 多粒度分块:

1. 文档级别

• 目的： 高级别摘要（整个文件）
• 尺寸： 最多8000个字符
• 粒度： document
• 用例： 快速概览

2. 递归分块

• 目的： 通用语义搜索
• 尺寸： 约700个标记，重叠度15%-20%
• 粒度： recursive
• 用例： 查准率与查全率的平衡

3. 代码感知分块（或：代码意识分块）

• 目的： 函数/类级别的精确度
• 尺寸： 变量（每个代码块对应一个函数/类）
• 粒度： code
• 用例： 代码搜索与导航

元数据提取：

文件可以包含带括号的标签：

[persona:dev] [project:example1]
This content is tagged for the dev persona and example1 project.

标签被提取并存储在 metadata 用于过滤的JSONB列。

测试

运行测试

# All tests
npm test

# With coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

# Specific file
npm test -- searchTool.test.ts

覆盖阈值

数据库集成测试

集成测试需要一个正在运行的 PostgreSQL 实例：

export DATABASE_URL=postgres://mcp:mcp@127.0.0.1:5432/mcp_vector_test
npm test -- --coverage

见 docs/testing.md 以获取详细指南。

开发指南

见 docs/contributing.md for：对于；为了；给

• 开发环境设置
• 编码规范（来自 AGENTS.md)
• Git工作流程和提交规范
• 拉取请求流程
• 如何添加新的MCP工具
• 解决常见问题

快速参考：

• 语言： TypeScript（严格模式）
• 风格： 每个文件对应一项职责，采用语义化命名
• 测试： 使用 Jest 进行 TDD，目标覆盖率≥85%
• 格式化： Prettier + ESLint（可译为“Prettier 加上 ESLint”或保持原样，因为这是两个工具的名称组合，直接翻译可能不够直观）
• 提交（Commits）： 约定式的提交（Conventional commits）feat:， fix:等

文档

故障排除

“无法连接到 PostgreSQL”

# Check if PostgreSQL is running
docker-compose ps postgres

# Check connection
psql $DATABASE_URL -c "SELECT 1"

# Verify credentials in .env

OpenAI API请求速率超出限制

# Check rate limits in OpenAI dashboard
# Reduce batch size in ingestion:
npm run ingest -- --embedding-batch-size 50

“端口3333已被占用”

# Find process using port
lsof -i :3333

# Kill process
kill -9 <PID>

# Or use different port
MCP_HTTP_PORT=3334 npm run dev

“搜索无结果”

# Verify embeddings exist
npm run tool:run -- db.list

# Re-ingest if needed
npm run ingest

# Check query embedding generation
DEBUG_MCP_HTTP=true npm run dev

版本历史

v0.1.0（当前版本）

状态： 已准备好投入生产（85%完成）

特点：

• ✅ 带有HTTP/SSE和stdio传输的MCP服务器
• ✅ 四种生产工具：db.list（数据库列表）、search（搜索）、fetch（获取）、sandbox.read（沙箱读取）
• ✅ 两个资源：语料库://信息，状态://健康
• ✅ 多粒度分块（文档、递归、代码感知）
• ✅ 每个项目独立数据库的多租户架构
• ✅ 带元数据过滤的IVFFlat向量索引
• ✅ 全面测试（290项测试，覆盖率80.54%）
• ✅ 使用 VectorStoreError 进行错误处理
• ✅ 代码质量：重复率低于5%，无代码异味（即代码规范且无不良编码习惯）

进行中：

• 🔄 将测试覆盖率提高到85%
• 🔄 性能优化（缓存、查询调优）

计划中：

• 📋 HTTP传输中的OAuth2.1认证
• 📋 用于频繁查询的Redis缓存层
• 📋 高级分块策略（滑动窗口、语义边界）
• 📋 PDF和音频的OCR/ASR支持

版本检查点（2025年10月12日）

已验证的依赖项：

• ✅ Node.js： 20.x 长期支持版本（活跃支持至2026年4月30日）
• ✅ PostgreSQL： 16.x（最新稳定版）
• ✅ pgvector： 0.7.0+（最新版本：0.7.4，发布于2024年8月5日）
• ✅ OpenAI API： 文本嵌入-3-小型（1536维）
• ✅ 对号（表示正确、确认或完成） MCP SDK： @modelcontextprotocol/sdk ^1.19.1（注：此句为包管理或版本控制相关的表述，直接翻译为中文即为“@modelcontextprotocol/sdk 的1.19.1版本或更高版本”，但在此上下文中，保持原样以体现其作为技术术语的特定含义）

下一个检查点： 在v1.0版本发布前（验证上游依赖）

未来改进

计划中的功能

• 认证： 支持OAuth 2.1的HTTP传输
• 缓存： 用于嵌入和查询缓存的Redis层
• 高级分块技术： 语义边界检测，滑动窗口
• 富媒体： PDF的OCR（光学字符识别），音频的ASR（自动语音识别）用于转录
• 监测： Prometheus指标，结构化日志记录
• UI（用户界面）: 用于项目管理和搜索的网页仪表板
• 演出 查询优化，连接池调优

研究领域

• 混合搜索（向量+关键词）
• 相关性反馈与重新排序
• 多模态嵌入（代码+文档）
• 实时摄入（文件监视器）

笔记

• 这是一个私有项目，仅限内部使用。不接受外部贡献/拉取请求（PRs）/问题追踪。

许可证

MIT 许可证 - 请参阅 许可证 详情如下

致谢

• 模型上下文协议 - MCP规范
• OpenAI（一家专注于人工智能研究的非营利性组织） 嵌入式API
• pgvector - PostgreSQL 向量扩展
• Drizzle ORM（注：Drizzle 通常指细雨，但在此上下文中，它可能是一个特定库或框架的名称，因此直接保留原样；ORM 是 Object-Relational Mapping 的缩写，即对象关系映射） - TypeScript ORM（对象关系映射）

支持

• 文档存储在本地 docs/ 目录。

使用TypeScript、PostgreSQL和OpenAI精心打造

计划实施

1. MCP 服务器（TypeScript + @modelcontextprotocol/sdk）
   • 在本地开发时通过标准输入输出（stdio）进行通信；部署在连接器隧道（如Cloudflare Tunnel）后，即可通过HTTPS提供服务。
   • 船只a（注：这里的“a”可能是指某个特定的船只名称或编号，根据上下文具体确定） server.ts 通过执行入口点 tsx/ts-node 正在开发中，并已编译准备好进行生产部署。
   • 注册工具： db.list （列出项目数据库）， search (纯文本语义查找)， fetch (检索块内容)，以及 sandbox.read （每个项目的直接文件读取次数）。
   • 表面资源/提示词，帮助ChatGPT选择角色并解释工具使用方法。
2. 向量存储（PostgreSQL + pgvector）
   • 为每个沙盒项目维护一个专用数据库mcp_vector_<project> （默认情况下）通过……进行初始化 npm run seed:projects 当你的本地Postgres服务正在运行时。
   • 每个数据库都提供了一个 embeddings 餐桌摆放（或“餐桌上放置”） id， file_path， chunk_text， embedding （向量），以及 metadata （用于标签数组、时间戳、用户角色/项目标签的JSONB）。
   • IVFFlat向量索引结合元数据上的GIN索引，以实现按用户角色/项目的高效过滤。
   • 会话级别 ivfflat.probes 设置为（来源于） IVFFLAT_PROBES （默认 10因此，即使数据集较小，人工神经网络（ANN）搜索也能返回结果 search 当需要更深入的检索时，该工具可以覆盖探测次数。
3. 摄入管道（或摄入流程）
   • 散步 sandbox/过滤掉二进制文件，解析带括号的元数据，并应用多粒度分块处理：
     • 文档级别的摘要，便于快速概览。
     • 对于通用语义搜索，采用递归方式将文本分割为约700个标记的块，且每个块之间有15%至20%的重叠。
     • 在适用时，使用格式感知的切片（代码级别为函数，Markdown级别为标题）。
   • 为每个块层级调用OpenAI嵌入API，并为行添加标签 granularity在将数据插入PostgreSQL之前，处理人员/项目标签以及跨度元数据。
   • 通过清除或软删除在摄入运行之间消失的文件的嵌入表示来解决删除问题。
   • 通过独立的命令行界面（CLI）暴露npm run ingest); 目前MCP表面为只读状态。
4. 连接器工作流
   • 设计为可与ChatGPT的开发者模式连接器进行注册，以便助手能够通过MCP工具协调具有角色意识的工作流程。

先决条件

• 带有TypeScript工具的Node.js 20.x长期支持（LTS）版本tsx， ts-node) 可用。
• 带有（某特性/插件/等）的 PostgreSQL 16.x pgvector 本地有0.7.x或更高版本的扩展可用；如果上游发布版本更新，请调整镜像标签。
• 根据您的要求，以下是原文内容的翻译：“OpenAI API密钥，可访问您配置的嵌入和GPT端点（默认目标）” gpt-4.1-nano （用于本地测试）。
• （可选）在将服务器暴露给ChatGPT时，使用ngrok或类似的隧道工具。
• 熟悉最新的OpenAI模型上下文协议服务器规范（2025年10月8日确认）以及GPT-4.1模型系列的发行说明，以确保终端兼容性。

在开始实施冲刺之前，请重新验证当前可用的GPT-4.1模型变体以及pgvector/PostgreSQL发布版本，以确保文档、配置和测试与生产环境实际情况相符。

本地运行

1. 确保 PostgreSQL（17.x 版本，带有 pgvector 扩展）正在运行 127.0.0.1:5432 以及其中的凭证 .env 比赛。
2. 运行迁移： npm run db:migrate （以及每个项目的种子，与 npm run seed:projects）。
3. 以开发模式启动MCP服务器： npm run dev （或 npm start （用于编译后的构建）。服务器监听在 http://127.0.0.1:3333/mcp。
4. （可选）启动 Cloudflare 隧道，以便外部客户端可以访问服务器： npm run stack:start -- --no-rebuild。
5. 在本地使用工具进行练习 npm run tool:run -- db.list， search等，在连接ChatGPT之前验证结果。

脚本（当前）

用于摄入的工具现已可用；请参阅 plan.md 第4节：剩余增强功能。

版本检查点（2025年10月8日）

• OpenAI模型GPT-4.1、GPT-4.1 mini 和 GPT-4.1 nano 仍可用于嵌入和摘要生成。在ChatGPT付费层级中，GPT-4.1 mini 现已取代GPT-4o mini，同时保持共享的速率限制不变。
• **PostgreSQL/pgvector（可译为“PostgreSQL/pgvector（扩展）”或保持原样，因为“pgvector”通常作为专有名词使用）**pgvector 0.7.4（发布于2024年8月5日）是最新公开可用的版本，并将在2025年10月6日的维护窗口期间集成到托管的PostgreSQL 17发行版中。
• MCP规范修订版2025-06-18引入了针对HTTP传输和结构化工具注解的OAuth2.1要求；stdio握手保持不变 initialize → result → notifications/initialized。

在发布版本前重新运行这些检查，以确认上游预期没有发生变化。

文件结构（预期）

.
├── plan.md                         # Detailed task checklist (current planning doc)
├── README.md                       # Project overview and setup guidance
├── package.json                    # npm metadata and scripts (to be expanded)
├── tsconfig.json                   # Strict TypeScript compiler configuration (planned)
├── server.ts                       # MCP server entrypoint (placeholder)
├── src/
│   ├── types/
│   │   └── index.ts                # Canonical domain/tool schemas shared across modules
│   ├── ingestion/
│   │   ├── walker.ts               # File discovery helpers
│   │   ├── metadata.ts             # Tag parsing utilities
│   │   └── ingest.ts               # Embedding pipeline orchestrator
│   ├── db/
│   │   ├── pool.ts                 # PostgreSQL client factory with pgvector setup
│   │   └── schema.sql              # Table + index creation statements
│   ├── server/
│   │   ├── createMcpServer.ts      # Registers search/fetch tools and MCP resources
│   │   └── __tests__/createMcpServer.test.ts
│   └── prompts/
│       └── personas.ts             # Persona prompt/resource definitions
├── docs/
│   ├── testing.md                  # Manual + automated test checklist (planned)
│   └── architecture.md             # Extended design notes (planned)
└── sandbox/                        # Source files to ingest into the vector store (never runtime/server code)
    └── ...

将运行时/服务器逻辑排除在外 sandbox/; 仅可食用（即仅适用于处理）的语料库文件应放在此处，以避免服务器对其自身代码进行索引。

共享类型库

所有运行时和测试模块都从共享库中导入域/工具模式 src/types 包。这确保了JSON模式、元数据接口和用户角色定义在服务器、数据摄入管道以及未来的客户端之间保持一致。代理应添加新的合约到 src/types/index.ts （或相关模块）并通过一个汇总文件重新导出它们，这样下游代码就无需在本地重新定义形状。参见 AGENTS.md 针对包含此要求的入职检查清单。

分块策略

• 文档摘要每个文件/角色提供一个高级别信息块，以便协调者快速概览。
• 递归基础块在所有文本格式中，使用约700个标记的片段，且片段间有15%至20%的重叠，以实现召回率与成本之间的平衡。
• 格式感知切片在结构重要的地方，额外的代码单元或标题级别块，每个都带有标签 granularity 因此，查询可以针对适当的详细程度。
• 人物定义文件（存储为 .json在分块处理之前，这些内容会被解析，以便其关键属性（语气、限制条件、目标）成为可搜索的元数据，同时原始JSON数据仍然可访问，以便进行完整检索。
• 运行时代码块大小和重叠阈值可通过（相关配置）进行设置 CHUNK_STRATEGY 以及相关的环境变量，因此实验无需更改代码。

编码规范

• 使用严格的编译器设置，将所有运行时逻辑用TypeScript编写；JavaScript仅用于生成产物。
• 保持模块专注——遵循“每个文件一个功能或类”的指南，并选择能描述意图的语义化文件名。
• 在共享库中集中管理类型（src/types/），通过导入定义而不是在特性或测试中重新声明它们。
• 使用 Jest 实践测试驱动开发（TDD）：在实现之前添加或更新失败的测试，并保持通过的测试套件达到约定的覆盖率阈值。
• 一旦配置到位，即遵守代码检查和格式化规范；未经审查，不得抑制规则。
• 看 docs/contributing.md 关于执行细节、工具指令以及审查期望。

未来的改进/增强

• 评估OCR/ASR工具，以便能够与文本来源一起处理PDF、图像和音频资产。
• 为长期运行的部署加强Cloudflare隧道配置，使用IP白名单或身份验证。
• 一旦核心MCP工具稳定下来，就通过Apps SDK输出模板探索更丰富的UI组件。

配置

1. 复制 .env.example to .env.
2. 更新占位符值：
   • OPENAI_API_KEY （嵌入和摘要所需的）。
   • PGHOST， PGPORT， PGDATABASE， PGUSER， PGPASSWORD （默认值与 docker-compose.yml）。

• OPENAI_EMBEDDING_MODEL / OPENAI_SUMMARY_MODEL （默认为 text-embedding-3-small 并且 gpt-4.1-mini; 提升到（或“置顶到”） text-embedding-3-large 如果你更倾向于使用高保真度的向量，并且能接受较慢的搜索速度。
• CHUNK_STRATEGY （默认 recursive-700（根据实验进行调整）。

3. 确保 vector 已安装扩展（CREATE EXTENSION IF NOT EXISTS vector;）。 启动SQL中的（内容/部分） db/init/001-create-extension.sql 在Docker Compose流程中，这会自动处理。
4. OpenAI密钥必须包含对Embeddings API的访问权限。如果您看到 insufficient_quota 错误，请确认组织已激活计费计划并已启用嵌入功能。
5. 故障排除技巧：
   • PostgreSQL 连接失败：确认 docker compose ps 显示 mcp-vector-db 健康，还有那个 pg_isready 成功。
   • 空查询结果：运行 npm run ingest 在添加文件到（某个地方/某个项目/某个系统等）之后 sandbox/ 因此，嵌入表示是可用的。
   • 大型语料库：集合 CHUNK_STRATEGY 到 recursive-1200 （或类似方法）以减少数据块数量，同时保持重叠在可控范围内。
   • 运行时拒绝创建数据库的权限 npm run seed:projects:
     • 原因：该 PGUSER 角色缺乏 CREATEDB 特权，但播种流程会为每个项目创建数据库。
     • 修复选项A（推荐）：授予 CREATEDB 为你的应用角色设置好后，然后运行数据播种（或初始化数据）：
       • psql -h 127.0.0.1 -U postgres -d postgres -c "ALTER ROLE mcp_user CREATEDB;"
     • 修复选项B（不更改角色）：设置仅用于数据库创建的独立管理员凭据，并保持数据库由您的应用程序角色所有：
       • 在 .env，添加 PGADMIN_USER/PGADMIN_PASSWORD （一个带有……的角色） CREATEDB）并且可选地 PGADMIN_DATABASE=postgres。
       • 确保 PGOWNER 设置为所需的拥有者（默认为 PGUSER)。
       • 重新运行 npm run seed:projects.

摄入工作流程

1. 通过……启动 PostgreSQL docker compose up -d db 并等待健康检查通过。
2. 跑 npm run ingest 遍历；穿越 sandbox/解析带括号的元数据标签，将Markdown/TypeScript/YAML内容分块，并从（某处）请求嵌入向量 text-embedding-3-small并将向量插入到PostgreSQL中（或更新已存在的向量）。
3. 摄入管道会移除在运行之间被删除或更改的文件的陈旧嵌入表示，以保持存储与（当前状态）一致 sandbox/.

MCP 工具（当前行为）

• db.list列出可用的项目数据库（源自 sandbox/<project> （目录）。首先调用此功能以选择 databaseId 被其他工具使用。
• search接受纯文本查询以及一个 databaseId在服务器端生成嵌入表示，并返回所选项目的经过清理的沙盒结果（ID、URI、代码片段、元数据）。
• fetch解析指定范围内的块标识符 databaseId 转换为完整的有效载荷内容，以便客户端可以读取底层文件。
• sandbox.read根据给定路径读取整个沙盒文件 databaseId （限制在≤256 KiB）并返回文本输出和结构化元数据。

通过Docker + Cloudflare暴露本地服务器

• docker-compose.yml 现在仅提供Cloudflare隧道（cloudflared）。 PostgreSQL 实例和 MCP 服务器在您的主机上运行（例如，通过 Homebrew + npm run dev）。
• 在首次运行之前，复制您的 mcp-vector 将隧道凭据JSON化（或“将隧道凭据转换为JSON格式”） cloudflared/credentials/mcp-vector.json导出原始证书 cloudflared tunnel login to cloudflared/cert.pem，并确保 .env 携带有效的OpenAI/Postgres值。
• 使用 npm run stack:start 对于独立发射或 npm run stack:start:follow 在启动时流式传输Cloudflare日志。隧道将流量转发到 http://host.docker.internal:3333因此，请确保MCP服务器在本地监听该端口。
• 跑 npm run stack:smoke 在启动服务器以发送一个 OPTIONS 尝试到 http://127.0.0.1:3333/mcp 并在通过隧道暴露之前确认当地已做好准备。
• 检查容器状态，使用 docker compose ps，查看日志使用 docker compose logs cloudflared，并通过（某种方式）关闭所有设备 docker compose down 当你完成后。
• MCP HTTP传输以无状态模式运行，因此客户端（包括ChatGPT）无需发送自定义会话头，只需发送标准的JSON-RPC请求 initialize 请求（向……） /mcp。

发展路线图（高层级）

• 完成需求对齐（OpenAI MCP规范、验收标准、用户角色元数据期望）。
• 搭建npm项目，安装依赖项，并提交基础的代码规范/测试工具配置。
• 实现PostgreSQL架构、辅助库以及数据摄入命令行界面。
• 构建MCP服务器入口点并暴露规范地址 search/fetch 工具对。
• 添加角色资源/提示和元数据驱动的工作流提示。
• 编写测试（单元测试+集成测试）并使用MCP Inspector进行验证。
• 船舶文件更新并准备ChatGPT连接器使用说明。

状态

规划进行中——按项目划分的数据库（db.list （数据库范围的工具）和初始化脚本已就绪；请继续 plan.md 对于剩余的分块处理和相关性改进。