Bg MCP Server

柏林集团MCP服务器

模型上下文协议（MCP）服务器，在VS Code和IntelliJ IDEA中向人工智能助手提供Berlin Group Open Finance API规范作为上下文信息。

概述

此MCP服务器从OpenAPI YAML文件和PDF文档中加载并索引柏林集团开放金融规范，使LLM能够在开放金融框架实施过程中提供准确、符合规范的指导。

服务器功能 先进的人工智能能力 包括：

• 语义搜索 通过ChromaDB进行智能、上下文感知的文档检索
• 图数据库 通过Neo4j探索API端点、模式和数据模型之间的复杂关系
• 矢量嵌入 用于跨PDF文档的自然语言查询
• 关系遍历 用于理解依赖关系和模式继承

特性

• 📚 完整的规范访问：加载所有柏林集团OpenAPI规范（AIS、PIS、PIIS、BASK、同意书等）
• 🔍 强大的搜索功能：跨端点、模式和PDF文档搜索
• 🎯 智能过滤：按方法、标记或规范筛选端点
• 📖 PDF支持：从实施指南中提取和搜索内容
• 🧠 语义搜索：使用ChromaDB向量嵌入进行自然语言查询的人工智能语义搜索
• 🕸️ 图数据库：Neo4j集成，用于探索复杂的关系和依赖关系
• 📊 关系遍历：在架构引用、端点依赖项和API互连之间导航
• ✂️ 智能文本分块：将PDF文档拆分为语义上有意义的块，以便更好地检索
• 🔄 自动回退：当ChromaDB或Neo4j不可用时，优雅地回退到内存存储
• 🛠️ 24个MCP工具：全面的工具集，包括12个核心工具+6个语义搜索工具+6个图形数据库工具
• 🔌 多IDE支持：适用于VS Code和IntelliJ IDEA

可用规格

服务器对以下柏林集团规范进行索引：

• 账户信息服务（AIS） v2.3
• 支付发起服务（PIS） v2.3
• 资金确认（PIIS） v2.3
• 银行账户状态服务（BASK） v2.2
• 同意管理 v2.1
• 数据字典 v2.3.1
• 支付更新状态中心（PUSH） v2.2

安装

先决条件

• Node.js v18或更高版本
• npm或纱线
• 支持MCP的VS Code或IntelliJ IDEA
• 可选的：用于语义搜索的ChromaDB服务器（默认在localhost:8000上运行）
• 可选的：用于图形查询的Neo4j数据库（默认在localhost:7687上运行）

设置

1. 克隆或导航到项目目录：

   cd path-of-the-repo/Berlin-group-mcp

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

配置

VS Code

1. 配置文件已在以下位置创建 .vscode/mcp-settings.json

1. 如果需要，请更新路径以匹配您的项目位置：

   {
     "mcpServers": {
       "berlin-group": {
         "command": "node",
         "args": [
           "absolute-path-of-the-repo/Berlin-group-mcp/build/index.js"
         ]
       }
     }
   }

1. 重新启动VS Code或重新加载窗口

1. Berlin Group工具现在应该可以在GitHub Copilot Chat上使用

智能J IDEA

看 INTELLIJ_SETUP.md 了解详细的配置说明。

依赖项

该项目使用以下关键依赖关系：

核心依赖关系

• @模型上下文协议/sdk （^1.0.4）：MCP协议实现
• js yaml （^4.1.0）：OpenAPI规范的YAML解析
• pdf解析 （^1.1.1）：PDF文档文本提取

高级功能

• 向量数据库 （^1.8.1）：用于语义搜索的矢量数据库客户端

- 启用基于AI的文档检索 - 可选：如果不可用，则回退到内存存储

• neo4j驱动程序 （^5.27.0）：Neo4j图形数据库驱动程序

- 启用复杂的关系查询 - 可选：如果不可用，则回退到内存图

开发依赖

• TypeScript （^5.7.3）：TypeScript编译器
• 玩笑 （^29.7.0）：测试框架
• 开玩笑的 （^29.1.2）：对Jest的TypeScript支持
• 所有主要依赖项的类型定义

所有依赖项都会自动安装 npm install.

可选：外部数据库配置

柏林集团MCP服务器可以选择使用外部数据库来增强功能。两者都是 完全可选 –服务器在不使用内存存储的情况下可以完美工作。

配置方法

服务器支持两种配置方法：

1. 环境变量 （推荐）：创建一个 .env 项目根目录中的文件
2. 直接配置：修改中的配置 src/index.ts

环境变量

复制 .env.example 文件到 .env 并自定义：

cp .env.example .env

然后编辑 .env 使用您的设置：

# ChromaDB Configuration (for Semantic Search)
CHROMA_HOST=localhost
CHROMA_PORT=8000
CHROMA_COLLECTION=berlin_group_pdfs

# OpenAI Configuration (for embeddings)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Neo4j Configuration (for Graph Database)
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j
NEO4J_MAX_POOL_SIZE=50
NEO4J_CONNECTION_TIMEOUT=60000

直接配置

或者，您可以直接在中修改配置 src/index.ts:

const indexer = new SpecificationIndexer({
  vectorStore: {
    chromaHost: 'localhost',
    chromaPort: 8000,
    collectionName: 'my_collection',
    embeddingModel: 'text-embedding-3-small'
  },
  graphStore: {
    uri: 'bolt://localhost:7687',
    username: 'neo4j',
    password: 'password',
    database: 'neo4j',
    maxConnectionPoolSize: 50,
    connectionAcquisitionTimeout: 60000
  }
});

ChromaDB（用于语义搜索）

ChromaDB使用向量嵌入在PDF文档中实现基于AI的语义搜索。

安装：

# Using pip
pip install chromadb

# Or using Docker
docker run -d -p 8000:8000 chromadb/chroma

默认配置：

• 主持人： localhost
• 端口： 8000
• 收藏： berlin_group_pdfs

服务器在初始化过程中会自动连接。如果ChromaDB不可用，语义搜索将退回到关键字匹配。

Neo4j（用于图形数据库）

Neo4j支持跨规范、端点和模式的复杂关系查询和图遍历。

安装：

# Using Docker (recommended)
docker run -d \
  -p 7475:7474 -p 7688:7687 \
  -e NEO4J_AUTH=neo4j/password \
  --name neo4j_berling_group_mcp \
  neo4j:latest

# Or download from https://neo4j.com/download/

默认配置：

• URI： bolt://localhost:7687
• 用户名： neo4j
• 密码： password
• 数据库： neo4j

服务器在初始化过程中会自动连接。如果Neo4j不可用，则使用内存中的图查询实现。

Neo4j浏览器访问： Neo4j运行后，访问浏览器界面 http://localhost:7474 要使图形可视化：

// Example queries in Neo4j Browser
MATCH (s:Specification)-[:DEFINES_ENDPOINT]->(e:Endpoint)
RETURN s, e LIMIT 25

MATCH（e：端点）-\[：USES_SCHEMA\]->（s：架构） 其中e.path包含“付款” 返回e，s

MATCH路径=（s1:架构）-\[：参考文献\*1..3\]->（s2:架构） 其中s1.name=“付款发起” 返回路径

### Embedding Providers

For production deployments with ChromaDB, consider using advanced embedding providers:

**OpenAI Embeddings** (highest quality):

// Set environment variable export OPENAI_API_KEY="your-api-key"

// Modify vectorStore.ts to use OpenAIEmbeddingProvider const embeddingProvider = new OpenAIEmbeddingProvider( process.env.OPENAI_API_KEY, 'text-embedding-3-small' // or 'text-embedding-3-large' );

**本地嵌入** （默认情况下，不需要API）：
该服务器包含一个内置的基于TF-IDF的嵌入提供程序，无需外部API即可工作。当没有配置其他提供程序时，它会自动使用。

### 部署场景

|场景| ChromaDB | Neo4j |可用工具|最适合|
|----------|----------|-------|-----------------|----------|
| **全栈** | ✅ 正在运行|✅ 运行|24个工具|生产、研究、复杂分析|
| **语义焦点** | ✅ 正在运行|❌ 不可用|18个工具|文档搜索，问答|
| **图形焦点** | ❌ 不可用|✅ 运行| 18个工具| API体系结构分析|
| **最小/发展** | ❌ 不可用|❌ 不可用|12个工具|开发，基本查询|

## 建筑

### 核心组件

柏林集团MCP服务器采用模块化架构构建，由几个专用组件组成：

#### 1. **YAML解析器** (`yamlParser.ts`)

从YAML文件中解析Berlin Group OpenAPI规范，提取：

- API端点（路径、方法、参数）
- 模式定义和数据模型
- 标签、描述和元数据
- 请求/响应规范

#### 2. **PDF解析器** (`pdfParser.ts`)

使用处理PDF文档文件 `pdf-parse` 图书馆：

- 从PDF文档中提取全文内容
- 执行基于关键字的文本搜索
- 提供文档摘要和元数据

#### 3. **文本块** (`textChunker.ts`)

实现矢量嵌入的智能文档分割：

- **递归字符分割**：在自然边界处打断文本（段落、句子、子句）
- **可配置块大小**：默认1000个字符，重叠200个字符，以保持上下文连续性
- **元数据保存**：跟踪源文件、块索引、节标题和页面估计值
- **语义连贯性**：尽可能避免在句中拆分以保持意思

#### 4. **向量存储** (`vectorStore.ts`)

使用ChromaDB管理语义搜索功能：

- **ChromaDB集成**：与ChromaDB服务器的可选连接，用于持久矢量存储
- **本地嵌入提供程序**：当外部API不可用时，内置TF-IDF式嵌入生成
- **OpenAI嵌入支持**：与OpenAI的嵌入模型（text-embedding-3-small、text-embeading-3-large）可配置集成
- **自动回退**：在ChromaDB服务器不可用时使用内存中的矢量存储
- **语义搜索**：具有相关性评分和距离度量的自然语言查询
- **元数据筛选**：在特定文件或文档部分中搜索

**矢量存储如何工作**:

1. PDF文档由文本块分割器分割成块
1. 每个块都转换为向量嵌入（384-3072维，具体取决于提供者）
1. 嵌入内容存储在ChromaDB集合或内存回退中
1. 用户查询使用相同的模型嵌入
1. 余弦相似度找到最相关的块
1. 结果按相关性得分（0.0到1.0）进行排名

#### 5. **图形存储** (`graphStore.ts`)

使用Neo4j管理图形数据库操作：

- **Neo4j集成**：可选连接到Neo4j数据库，用于复杂的关系查询
- **内存回退**：Neo4j不可用时完成图实现
- **连接管理**：处理驱动程序生命周期、会话和事务
- **CRUD操作**：使用类型化接口创建/读取节点和关系
- **Cypher查询执行**：直接访问Neo4j强大的查询语言
- **统计**：提供节点计数、关系和图形密度的度量

**图形节点类型**:

- **规格**：OpenAPI规范元数据（标题、版本、描述）
- **端点**：具有HTTP方法的API路径
- **模式**：数据模型和类型定义
- **财产**：具有类型和约束的架构字段
- **参数**：请求参数（查询、标头、路径、cookie）
- **响应**：带有状态代码的HTTP响应定义
- **标签**：端点分类

**图形关系类型**:

- `DEFINES_ENDPOINT`：规格→ 端点
- `DEFINES_SCHEMA`：规格→ 模式
- `HAS_PARAMETER`：端点→ 参数
- `HAS_RESPONSE`：端点→ 响应
- `USES_SCHEMA`：端点/参数/响应→ 模式
- `REFERENCES`：架构→ 模式（用于$ref关系）
- `HAS_PROPERTY`：架构→ 财产
- `TAGGED_WITH`：端点→ Tag

#### 6. **图形索引器** (`graphIndexer.ts`)

将OpenAPI规范转换为图结构：

- **规范索引**：为每个加载的规范文件创建节点
- **端点提取**：使用完整详细信息分析所有API终结点
- **模式映射**：提取所有数据模型及其属性
- **建立关系**：将端点连接到架构、参数和响应
- **指代消解**：如下 `$ref` 构建模式依赖关系图的指针
- **进度跟踪**：在索引操作期间提供实时反馈
- **错误处理**：优雅地处理格式错误的规范

**索引过程**:

1. 从以下位置加载YAML文件 `yml_files/` 目录
1. 为每个文件创建规范节点
1. 提取并创建端点节点
1. 提取并创建具有属性的架构节点
1. 在所有实体之间建立关系
1. 索引到Neo4j或内存存储中

#### 7. **图模型** (`graphModels.ts`)

定义用于类型安全图操作的TypeScript接口：

- 节点接口（SpecificationNode、EndpointNode、SchemaNode等）
- 关系类型枚举
- 查询结果类型（GraphTraversalResult、PatternSearchResult等）
- 用于创建节点的DTO类型
- ID生成和引用提取的实用功能

#### 8. **规范索引器** (`indexer.ts`)

编排所有组件并提供统一的API：

- 协调YAML解析器、PDF解析器、向量存储和图索引器
- 管理初始化顺序和错误处理
- 提供高级搜索和查询方法
- 处理可选服务不可用时的回退情况
- 汇总所有子系统的统计数据

### 数据流

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ YAML Files │────>│ YAML Parser │────>│ Graph Indexer │ │ (OpenAPI) │ │ │ │ │ └─────────────────┘ └──────────────────┘ └────────┬────────┘ │ v ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ PDF Files │────>│ PDF Parser + │────>│ Vector Store │ │ (Documentation) │ │ Text Chunker │ │ (ChromaDB) │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ v ┌──────────────────────────┐ │ Specification Indexer │ │ (Unified Interface) │ └────────────┬─────────────┘ │ v ┌──────────────────────────┐ │ MCP Server Tools │ │ (24 Tools Available) │ └──────────────────────────┘

### 回退机制

该服务器设计用于各种部署场景：

1. **全栈** （ChromaDB+Neo4j）：

   - 所有24种可用工具
   - 最佳性能和能力
   - 基于持久向量的语义搜索
   - 使用Cypher进行复杂的图形查询

1. **仅矢量** （ChromaDB，无Neo4j）：

   - 18个可用工具（核心+语义搜索）
   - 图查询在内存中的实现
   - 适用于以语义搜索为中心的用例

1. **仅图形** （Neo4j，无ChromaDB）：

   - 18个可用工具（核心+图形数据库）
   - 语义搜索退回到关键字匹配
   - 有利于关系探索用例

1. **最小化** （无外部数据库）：

   - 12个核心工具可用
   - 所有操作都使用内存存储
   - 仅基于关键字的搜索
   - 适用于基本查询和开发

服务器在初始化期间自动检测可用服务，并相应地调整其功能。通过统计数据和状态端点通知用户哪些功能可用。

## 可用工具

服务器提供 **24个MCP工具** 分为三类：

### 核心工具（12个工具）

#### 搜索和发现

- **`search_endpoints`** -搜索所有规范中的API端点

Example: "Find all payment endpoints"

- **`search_schemas`** -搜索数据模式和模型

Example: "Find schemas related to transaction"

- **`search_pdf_documentation`** -使用关键字匹配搜索PDF文档

Example: "Search for SCA requirements"

- **`search_all`** -跨所有来源（端点、模式、PDF）的全面关键字搜索

Example: "Find everything about consent"

#### 端点信息

- **`get_endpoint_details`** -获取特定端点的详细信息

Parameters: path, method Example: path="/v1/accounts", method="GET"

- **`filter_endpoints_by_tag`** -按标签筛选端点

Example: tag="accounts"

- **`filter_endpoints_by_method`** -按HTTP方法筛选端点

Example: method="POST"

#### 模式信息

- **`get_schema`** -获取特定的架构定义

Parameters: schemaName, specFile (optional) Example: schemaName="AccountDetails"

#### 规格管理

- **`list_specifications`** -列出所有可用的OpenAPI规范

- **`get_specification_details`** -获取特定规格的全面详细信息

Parameters: fileName

- **`list_pdf_documents`** -列出所有可用的PDF文档

- **`get_statistics`** -获取已加载规格的基本统计信息

### 语义搜索工具（6个工具）

这些工具使用ChromaDB和向量嵌入进行智能、上下文感知的文档检索。当ChromaDB不可用时，它们会自动回退到基于关键字的搜索。

- **`search_pdf_semantic`** -在PDF文档中执行语义搜索

Parameters: query (string), topK (number, default: 10) Example: "What are the authentication requirements for payment initiation?"

How it works: - Converts your natural language query into a vector embedding - Finds the most semantically similar document chunks - Returns results ranked by relevance score (0.0-1.0) - Understands synonyms and related concepts (e.g., "authenticate" matches "authorization")

- **`search_pdf_semantic_filtered`** -使用元数据过滤器的语义搜索

Parameters: query (string), fileName (optional), section (optional), topK (optional) Example: query="SCA exemptions", fileName="Implementation_Guide.pdf"

Use cases: - Search within a specific document - Filter by document section - Narrow results to relevant portions

- **`search_all_semantic`** -跨所有来源的全面语义搜索

Parameters: query (string), topK (number, default: 10) Example: "How do I handle declined payments?"

Returns: - Matching endpoints (keyword search) - Matching schemas (keyword search) - Semantically similar PDF content (vector search)

- **`get_vector_store_stats`** -获取矢量存储统计信息

Returns: - enabled: Whether vector store is operational - totalChunks: Number of indexed document chunks - collectionName: ChromaDB collection name - isInMemory: Whether using in-memory fallback

### 图形数据库工具（6个工具）

这些工具使用Neo4j来探索规范、端点、模式和数据模型之间的复杂关系。当Neo4j不可用时，他们使用内存图实现。

- **`graph_find_related_schemas`** -通过$ref引用查找相关模式

Parameters: schemaName (string), specFile (optional), maxDepth (number, default: 3) Example: schemaName="AccountReference"

Use cases: - Understand schema inheritance hierarchies - Find all schemas that reference a particular type - Discover composed data models - Map schema dependencies

- **`graph_get_endpoint_dependencies`** -获取API终结点的所有依赖项

Parameters: path (string), method (string), specFile (optional) Example: path="/v1/payments/sepa-credit-transfers", method="POST"

Returns: - All request parameters (query, header, path, body) - Request body schema and nested schemas - All possible response codes and their schemas - Complete dependency tree

- **`graph_traverse_relationships`** -使用过滤器执行自定义图遍历

Parameters: - startNodeType: Type of starting node (Specification, Endpoint, Schema, etc.) - startNodeFilter: Property filters (e.g., {name: "AccountReference"}) - relationshipTypes: Optional list of relationship types to follow - maxDepth: Maximum traversal depth (default: 3)

Example: startNodeType="Schema", startNodeFilter={name: "PaymentInitiation*"}, relationshipTypes=["REFERENCES", "USES_SCHEMA"]

Use cases: - Custom relationship exploration - Multi-hop dependency analysis - Pattern-based graph queries

- **`graph_get_specification_graph`** -获取规格的完整图表

Parameters: fileName (string) Example: fileName="BG_oFA_PIS_Version_2.3_20251128.openapi.yaml"

Returns: - All endpoints in the specification - All schemas and their properties - All relationships between entities - Complete specification structure as a graph

- **`graph_search_by_pattern`** -按属性模式搜索图节点

Parameters: - nodeType: Type of node to search - pattern: Property pattern with wildcards (e.g., {path: "/v1/accounts*"}) - limit: Maximum results (default: 50)

Example: nodeType="Endpoint", pattern={path: "/v1/payments/*", method: "POST"}

Supports wildcards: - {name: "*Account*"} - Contains "Account" - {path: "/v1/accounts*"} - Starts with "/v1/accounts" - {method: "POST"} - Exact match

- **`get_graph_store_stats`** -获取图形数据库统计信息

Returns: - enabled: Whether graph store is operational - usingNeo4j: Whether connected to Neo4j (true) or using in-memory (false) - Node counts by type (Specification, Endpoint, Schema, etc.) - Relationship counts by type - Indexing metrics (duration, errors) - Graph density metrics

### 工具选择指南

**在以下情况下使用核心工具：**

- 您需要精确的端点路径或模式名称
- 您想按标签或HTTP方法进行筛选
- 您正在寻找具体的规格细节

**在以下情况下使用语义搜索工具：**

- 你有自然语言问题
- 您正在跨文档探索概念
- 你不知道确切的术语
- 你想要AI驱动的相关性排名

**在以下情况下使用图形数据库工具：**

- 你需要了解关系和依赖关系
- 您正在探索模式继承
- 您想分析端点复杂性
- 您需要遍历多级引用

## 使用示例

### 使用GitHub Copilot编写VS代码

#### 基本查询

You: "What endpoints are available for account information?" Copilot: [Uses search_endpoints tool to find AIS endpoints]

You: "Show me the schema for payment initiation request" Copilot: [Uses search_schemas tool to find payment schemas]

#### 语义搜索查询

You: "How do I implement Strong Customer Authentication?" Copilot: [Uses search_pdf_semantic to find relevant SCA documentation with AI ranking]

You: "What are the requirements for payment authorization?" Copilot: [Uses search_all_semantic to find endpoints, schemas, and semantically related PDF content]

You: "Find information about transaction status in the PIS specification" Copilot: [Uses search_pdf_semantic_filtered with fileName filter]

#### 图形数据库查询

You: "What schemas does AccountReference depend on?" Copilot: [Uses graph_find_related_schemas to traverse schema relationships]

You: "Show me all dependencies for the payment initiation endpoint" Copilot: [Uses graph_get_endpoint_dependencies to get parameters, request/response schemas]

You: "Find all endpoints that use the Amount schema" Copilot: [Uses graph_traverse_relationships starting from Amount schema]

You: "Get the complete API structure for the AIS specification" Copilot: [Uses graph_get_specification_graph to return full specification graph]

#### 高级分析

You: "Compare the complexity of payment endpoints vs account endpoints" Copilot: [Uses graph_get_endpoint_dependencies for multiple endpoints and compares]

You: "What are all the possible error responses for account endpoints?" Copilot: [Uses graph_traverse_relationships to find all response schemas]

You: "Show me all schemas that contain PII (personally identifiable information)" Copilot: [Uses search_pdf_semantic to find PII references, then graph_search_by_pattern to find related schemas]

### 程序化使用

服务器也可以通过MCP协议以编程方式使用：

// Example tool call { "method": "tools/call", "params": { "name": "search_endpoints", "arguments": { "query": "payment" } } }

## 项目结构

Berlin-group-mcp/ ├── src/ │ ├── index.ts # Main MCP server with 24 tool definitions │ ├── indexer.ts # Specification indexer orchestrating all components │ ├── yamlParser.ts # OpenAPI YAML parser │ ├── pdfParser.ts # PDF document parser │ ├── textChunker.ts # Intelligent text chunking for vector embeddings │ ├── vectorStore.ts # ChromaDB integration for semantic search │ ├── graphStore.ts # Neo4j integration and in-memory graph store │ ├── graphIndexer.ts # Graph database indexer │ └── graphModels.ts # TypeScript interfaces for graph entities ├── yml_files/ # Berlin Group OpenAPI specs (7 specifications) │ ├── BG_oFA_AIS_Version_2.3_20250818.openapi.yaml │ ├── BG_oFA_PIS_Version_2.3_20251128.openapi.yaml │ ├── BG_oFA_PIIS_Version_2.3_20250818.openapi.yaml │ ├── BG_oFA_BASK_Version_2.2_20251128.openapi.yaml │ ├── BG_oFA_Consent_Version_2.1_20251128.openapi.yaml │ ├── BG_oFA_dataDictionary_Version_2.2.6_20250818.openapi.yaml │ └── BG_oFA_PUSH_Version_2.2_20250818.openapi.yaml ├── pdf_files/ # PDF documentation (implementation guides, frameworks) ├── tests/ │ ├── unit/ # Unit tests for individual components │ │ ├── vectorStore.test.ts │ │ ├── graphStore.test.ts │ │ ├── graphIndexer.test.ts │ │ ├── graphModels.test.ts │ │ └── textChunker.test.ts │ └── integration/ # Integration tests │ ├── semanticSearch.test.ts │ └── graphSearch.test.ts ├── build/ # Compiled JavaScript (generated) ├── docs/ # Architecture documentation and diagrams │ └── architecture/ │ └── diagrams/ # PlantUML diagrams for system architecture ├── postman/ # Postman collection for testing MCP tools ├── package.json # Dependencies: chromadb, neo4j-driver, pdf-parse, etc. ├── tsconfig.json ├── jest.config.js # Test configuration ├── .vscode/ │ └── mcp-settings.json # VS Code MCP configuration ├── INTELLIJ_SETUP.md # IntelliJ configuration guide └── README.md

## 发展

### 运行测试

该项目包括综合单元和集成测试：

Run all tests

npm test

Run tests in watch mode

npm run test:watch

Run with coverage report

npm run test:coverage

**测试覆盖范围：**

- **单元测试**: `vectorStore.test.ts`, `graphStore.test.ts`, `graphIndexer.test.ts`, `graphModels.test.ts`, `textChunker.test.ts`
- **集成测试**: `semanticSearch.test.ts`, `graphSearch.test.ts`

### 观看模式

要根据文件更改自动重建，请执行以下操作：

npm run watch

### 调试

使用Node.js检查器调试服务器：

npm run inspector

### 添加新规格

1. 将YAML文件添加到 `yml_files/` 目录
1. 将PDF文件添加到 `pdf_files/` 目录
1. 重建项目： `npm run build`
1. 重新启动MCP服务器（重新加载VS代码或重新启动IDE）
1. 新规格将在下次启动时自动索引

### 扩展服务器

**添加新工具：**

1. 在中定义工具架构 `src/index.ts` 工具阵列
1. 在中添加处理程序 `CallToolRequestSchema` 处理器
1. 在中实现业务逻辑 `src/indexer.ts`
1. 更新README文档

**添加新的嵌入提供程序：**

1. 实施 `EmbeddingProvider` 接口在 `src/vectorStore.ts`
1. 添加 `embed()` 和 `embedQuery()` 方法
1. 在中配置 `src/indexer.ts` 或通过环境变量

**自定义图形架构：**

1. 在中添加新节点类型 `src/graphModels.ts`
1. 在中添加关系 `RelationshipType` 枚举
1. 更新中的索引逻辑 `src/graphIndexer.ts`
1. 在中添加查询方法 `src/graphStore.ts`

## 故障排除

### 服务器未启动

1. **检查Node.js版本**: `node --version` （应该是v18+）
1. **验证构建已完成**: `ls -la build/` （应该看到.js文件）
1. **检查错误**：查看VS代码开发人员工具控制台（帮助→ 切换开发人员工具）
1. **重建**: `npm run build`

### 工具未出现

1. **确保MCP设置文件存在**：检查 `.vscode/mcp-settings.json`
1. **验证路径是否正确**：确保路径 `build/index.js` 绝对正确
1. **完全重新启动VS代码**：关闭所有窗口并重新打开
1. **查看GitHub副本**：确保Copilot已启用并正常工作
1. **检查控制台日志**：打开开发人员工具，查找MCP连接错误

### 搜索无结果

1. **验证YAML和PDF文件是否存在**:

ls -la yml_files/ pdf_files/

1. **检查服务器日志**：在控制台中查找初始化错误
1. **确保文件可读**：检查文件权限
1. **尝试重新索引**：删除并重新生成： `rm -rf build && npm run build`

### 语义搜索不起作用

1. **检查ChromaDB是否正在运行** （可选）：

curl http://localhost:8000/api/v1/heartbeat

1. **查看初始化日志**：应看到“矢量存储中的索引X PDF块”
1. **检查回退模式**：如果ChromaDB不可用，服务器将回退到关键字搜索
1. **验证矢量存储统计数据**：使用 `get_vector_store_stats` 工具
1. **检查ChromaDB日志** （如果通过Docker运行）：

docker logs

### 图形数据库不工作

1. **检查Neo4j是否正在运行** （可选）：

curl http://localhost:7474 # Or check Docker: docker ps | grep neo4j

1. **验证凭据**：默认值为 `neo4j/neo4j` （首次登录时更改）
1. **查看初始化日志**：应看到“图形索引完成：X规格，Y端点，Z模式”
1. **检查回退模式**：如果Neo4j不可用，服务器将使用内存图
1. **验证图形存储统计数据**：使用 `get_graph_store_stats` 工具
1. **测试Neo4j连接**:

# Using cypher-shell cypher-shell -u neo4j -p your-password

### 性能问题

1. **大型PDF文件**：考虑拆分成更小的文档
1. **ChromaDB速度慢**:
   - 使用本地部署而不是远程部署
   - 减少 `topK` 语义搜索中的参数
   - 考虑更快的嵌入提供商
1. **Neo4j速度慢**:
   - 检查是否创建了索引
   - 减少 `maxDepth` 图内遍历
   - 优化Cypher查询
1. **内存使用率高**:
   - 使用外部数据库（ChromaDB+Neo4j）而不是内存中的数据库
   - 减少加载的规格数量

### 连接错误

**ChromaDB连接被拒绝：**

Error: connect ECONNREFUSED 127.0.0.1:8000

解决方案：ChromaDB未运行或在其他端口上运行。服务器将自动回退到内存模式。

**Neo4j连接失败：**

Neo4jError: Could not connect to bolt://localhost:7687

解决方案：Neo4j未运行或凭据错误。服务器将自动回退到内存模式。

### 权限问题

If index.js is not executable

chmod +x build/index.js

If YAML/PDF files are not readable

chmod -R 644 yml_files/*.yaml pdf_files/*.pdf

### 调试提示

1. **启用详细日志记录**：设置 `NODE_ENV=development` 启动服务器之前
1. **检查初始化顺序**：服务器日志显示每个阶段
1. **测试单个组件**:

npm test -- vectorStore.test.ts npm test -- graphStore.test.ts

1. **验证工具可用性**：使用 `get_statistics`, `get_vector_store_stats`, `get_graph_store_stats` 工具
1. **检查MCP通信**：在开发人员控制台中查找JSON-RPC消息

### 常见错误消息

|错误|原因|解决方案|
|-------|-------|----------|
|“规格尚未加载”|服务器仍在初始化|等待5-10秒，然后重试|
|“语义搜索不可用”|ChromaDB未连接|正常，退回关键字搜索|
|“图形存储不可用”|Neo4j未连接|正常，回退到内存中|
|“找不到集合”| ChromaDB集合丢失|服务器在启动时自动创建它|
|“身份验证失败”|Neo4j凭据错误|在代码中更新凭据或使用默认凭据|

## 技术细节

### MCP协议

该服务器实现了模型上下文协议规范（2025-11-25）：

- **工具**：24个工具分为核心、语义搜索和图形数据库类别
- **资源**：通过以下方式直接访问规范文件 `berlin-group://` URI方案
- **运输**：用于IDE集成的基于stdio的通信

### 组件架构

#### 解析器功能

- **YAML解析器**:

  - 从OpenAPI 3.0+规范中提取路径、操作、模式和组件
  - 手柄 `$ref` 指针分辨率
  - 验证规范结构
  - 索引标签、参数和响应

- **PDF解析器**:

  - 用途 `pdf-parse` 文本提取库
  - 保留文档结构和元数据
  - 启用全文关键字搜索
  - 提供页码估计

- **文本块**:

  - 递归字符分割算法
  - 可配置的块大小（默认：1000个字符）和重叠（默认：200个字符）
  - 保持跨块的语义连贯性
  - 保留元数据（文件名、节、页码）

#### 矢量存储实现

- **ChromaDB集成**:

  - 与ChromaDB服务器的HTTP客户端连接
  - 基于收藏的文档组织
  - 元数据过滤支持
  - 余弦相似度用于相关性评分

- **嵌入提供者**:

  - **本地嵌入提供者**：基于TF IDF，384个维度，无外部依赖
  - **OpenGL硬件提供商**：基于GPT的1536或3072维度，需要API密钥
  - 自定义提供商的可插拔架构

- **搜索算法**:

  - 查询嵌入生成
  - K-最近邻（KNN）搜索
  - 距离度量（余弦相似度，L2距离）
  - 相关性得分归一化（0.0至1.0）

#### 图形存储实现

- **Neo4j集成**:

  - Bolt协议驱动程序（neo4j驱动程序v5.27.0）
  - 连接池提高性能
  - 交易管理
  - Cypher查询执行

- **图形架构**:

Nodes: Specification, Endpoint, Schema, Property, Parameter, Response, Tag Relationships: DEFINES_ENDPOINT, DEFINES_SCHEMA, HAS_PARAMETER, HAS_RESPONSE, USES_SCHEMA, REFERENCES, HAS_PROPERTY, TAGGED_WITH

- **内存回退**:

  - 使用地图完成图形实现
  - 与Neo4j实现相同的API
  - 支持所有查询模式
  - 适用于开发和测试

#### 索引过程

1. **初始化** （平行）：

   - 加载YAML文件→ 解析规范→ 提取端点/模式
   - 加载PDF文件→ 解析文档→ 块状文本→ 生成嵌入

1. **矢量存储索引**:

   - 将所有PDF文档分块（典型值：每份文档200-500块）
   - 为每个块生成嵌入
   - 使用元数据存储在ChromaDB中
   - 生成搜索索引

1. **图形存储索引**:

   - 创建规范节点
   - 创建具有关系的端点节点
   - 创建具有属性的架构节点
   - 创建参数和响应节点
   - 为$ref指针建立引用关系
   - 创建标记节点和关系

1. **错误处理**:

   - 如果数据库不可用，则性能会下降
   - 索引进度的详细记录
   - 不停止进程的错误收集
   - 回退到内存存储

### 演出

- **初始加载时间**:

  - YAML解析：~500ms（7种规范）
  - PDF解析：~1-2s（取决于文件数量/大小）
  - 向量索引：~2-5s（取决于块计数和嵌入提供者）
  - 图索引：~1-3s（取决于数据库连接）
  - **总计**：约5-10秒用于完全初始化

- **查询性能**:

  - 关键字搜索：\<10ms（内存搜索）
  - 语义搜索：50-200ms（取决于ChromaDB响应时间和top-k）
  - 图形查询：10-100ms（简单查询），100-500ms（复杂遍历）
  - 内存回退：大多数操作\<50ms

- **内存使用**:

  - 基本（规格）：~20-30MB
  - 矢量存储（内存中）：+30-50MB
  - 图形存储（内存中）：+20-40MB
  - **总计**：~70-120MB（不含外部数据库）
  - 使用外部数据库：~30-50MB（外部存储数据）

- **可扩展性**:

  - 可处理100多种规格
  - 支持1000+个PDF页面
  - 使用Neo4j扩展图形查询（数百万节点）
  - ChromaDB的矢量搜索规模（数百万个块）

## 快速参考

### 工具类别摘要

|类别|计数|目的|需要|
|----------|-------|---------|----------|
| **核心工具** |12|基本搜索、过滤、规范访问|无（内置）|
| **语义搜索** |6|AI支持的文档检索、自然语言查询|ChromaDB（可选）|
| **图数据库** |6|关系探索、依赖分析|Neo4j（可选）|
| **总计** | **24** |完整的规范分析工具包|仅限Node.js|

### 主要特征比较

|功能|无数据库|带ChromaDB |带Neo4j |两者都有|
|---------|------------------|---------------|------------|-----------|
|端点搜索|✅ 关键字|✅ 关键字|✅ 关键字|✅ 关键字|
|架构搜索|✅ 关键字|✅ 关键字|✅ 关键字|✅ 关键字|
|PDF搜索|✅ 关键字|✅ 语义+关键字|✅ 关键字|✅ 语义+关键字|
|架构关系|✅ 在记忆中|✅ 在记忆中|✅ Neo4j图形|✅ Neo4j图形|
|端点依赖关系|✅ 在记忆中|✅ 在记忆中|✅ Neo4j图形|✅ Neo4j图形|
|图形遍历|✅ 有限|✅ 有限|✅ 完整密码|✅ 完整密码|
|性能|良好|优秀（PDF）|优秀（图表）|优秀|
|内存使用量|~120MB|~70MB|~80MB|~50MB|

### 常见查询备忘单

// Find endpoints "search for payment endpoints" → Uses: search_endpoints

// Find schemas "show me the AccountDetails schema" → Uses: get_schema or search_schemas

// Natural language search (semantic) "how to handle authentication errors?" → Uses: search_pdf_semantic

// Find related schemas "what schemas does PaymentInitiation reference?" → Uses: graph_find_related_schemas

// Analyze endpoint "what are all the parameters and responses for POST /v1/payments?" → Uses: graph_get_endpoint_dependencies

// Explore relationships "show me all schemas that use Address type" → Uses: graph_traverse_relationships

// Get overview "show me statistics about the loaded specifications" → Uses: get_statistics, get_vector_store_stats, get_graph_store_stats

## 许可证

麻省理工学院

## 参考文献

- [模型上下文协议](https://modelcontextprotocol.io/) -MCP规范和文件
- [柏林集团开放金融](https://www.berlin-group.org/) -柏林集团官方网站
- [MCP SDK文档](https://github.com/modelcontextprotocol/sdk) -MCP的TypeScript SDK
- [ChromaDB文档](https://docs.trychroma.com/) -用于人工智能应用的矢量数据库
- [Neo4j文档](https://neo4j.com/docs/) -图形数据库平台
- [OpenAPI规范](https://swagger.io/specification/) -API规范格式

## 贡献

欢迎投稿！请确保：

- TypeScript代码遵循项目约定
- 所有工具都有适当的错误处理
- 文档已针对新功能进行了更新
- 为新组件添加了测试（中的单元测试 `tests/unit/`，集成测试 `tests/integration/`)
- 新的嵌入提供商实现了 `EmbeddingProvider` 接口
- 新的图形节点类型已添加到 `graphModels.ts`
- README更新了示例和使用说明

### 贡献领域

- 其他嵌入提供商（Cohere、HuggingFace等）
- 增强的图形查询功能
- 柏林集团的其他规格
- 性能优化
- 其他MCP工具
- 文档改进

## 支持

对于问题或疑问：

1. 检查故障排除部分
1. 审查MCP文件
1. 查看柏林集团规范文件