使用说明

柏林集团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上运行）

设置

克隆或导航到项目目录：
```
cd path-of-the-repo/Berlin-group-mcp
```
安装依赖项：
```
npm install
```
构建项目：
```
npm run build
```

配置

VS Code

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

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

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

重新启动VS Code或重新加载窗口
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服务器可以选择使用外部数据库来增强功能。两者都是 完全可选 –服务器在不使用内存存储的情况下可以完美工作。

配置方法

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

环境变量 （推荐）：创建一个 .env 项目根目录中的文件
直接配置：修改中的配置 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):
```typescript
// 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服务器不可用时使用内存中的矢量存储
语义搜索：具有相关性评分和距离度量的自然语言查询
元数据筛选：在特定文件或文档部分中搜索

矢量存储如何工作:

PDF文档由文本块分割器分割成块
每个块都转换为向量嵌入（384-3072维，具体取决于提供者）
嵌入内容存储在ChromaDB集合或内存回退中
用户查询使用相同的模型嵌入
余弦相似度找到最相关的块
结果按相关性得分（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 构建模式依赖关系图的指针
进度跟踪：在索引操作期间提供实时反馈
错误处理：优雅地处理格式错误的规范

索引过程:

从以下位置加载YAML文件 yml_files/ 目录
为每个文件创建规范节点
提取并创建端点节点
提取并创建具有属性的架构节点
在所有实体之间建立关系
索引到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)    │
                                             └──────────────────────────┘

回退机制

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

全栈（ChromaDB+Neo4j）：
- 所有24种可用工具
- 最佳性能和能力
- 基于持久向量的语义搜索
- 使用Cypher进行复杂的图形查询
仅矢量 （ChromaDB，无Neo4j）：
- 18个可用工具（核心+语义搜索）
- 图查询在内存中的实现
- 适用于以语义搜索为中心的用例
仅图形 （Neo4j，无ChromaDB）：
- 18个可用工具（核心+图形数据库）
- 语义搜索退回到关键字匹配
- 有利于关系探索用例
最小化 （无外部数据库）：
- 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

添加新规格

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

扩展服务器

添加新工具：

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

添加新的嵌入提供程序：

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

自定义图形架构：

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

故障排除

服务器未启动

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

工具未出现

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

搜索无结果

验证YAML和PDF文件是否存在:
```
ls -la yml_files/ pdf_files/
```
检查服务器日志：在控制台中查找初始化错误
确保文件可读：检查文件权限
尝试重新索引：删除并重新生成： rm -rf build && npm run build

语义搜索不起作用

检查ChromaDB是否正在运行 （可选）：
```
curl http://localhost:8000/api/v1/heartbeat
```
查看初始化日志：应看到“矢量存储中的索引X PDF块”
检查回退模式：如果ChromaDB不可用，服务器将回退到关键字搜索
验证矢量存储统计数据：使用 get_vector_store_stats 工具
检查ChromaDB日志 （如果通过Docker运行）：
```
docker logs <chromadb-container-id>
```

图形数据库不工作

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

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

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

测试Neo4j连接:

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

性能问题

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

调试提示

启用详细日志记录：设置 NODE_ENV=development 启动服务器之前
检查初始化顺序：服务器日志显示每个阶段

测试单个组件:

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

验证工具可用性：使用 get_statistics, get_vector_store_stats, get_graph_store_stats 工具
检查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
- 支持所有查询模式
- 适用于开发和测试

索引过程

初始化 （平行）：
- 加载YAML文件→ 解析规范→ 提取端点/模式
- 加载PDF文件→ 解析文档→ 块状文本→ 生成嵌入
矢量存储索引:
- 将所有PDF文档分块（典型值：每份文档200-500块）
- 为每个块生成嵌入
- 使用元数据存储在ChromaDB中
- 生成搜索索引
图形存储索引:
- 创建规范节点
- 创建具有关系的端点节点
- 创建具有属性的架构节点
- 创建参数和响应节点
- 为$ref指针建立引用关系
- 创建标记节点和关系
错误处理:
- 如果数据库不可用，则性能会下降
- 索引进度的详细记录
- 不停止进程的错误收集
- 回退到内存存储

演出

初始加载时间:
- 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

许可证

麻省理工学院

参考文献

模型上下文协议 -MCP规范和文件
柏林集团开放金融 -柏林集团官方网站
MCP SDK文档 -MCP的TypeScript SDK
ChromaDB文档 -用于人工智能应用的矢量数据库
Neo4j文档 -图形数据库平台
OpenAPI规范 -API规范格式

贡献

欢迎投稿！请确保：

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

贡献领域

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

支持

对于问题或疑问：

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