使用说明

知识服务器

一个专门的MCP（模型上下文协议）服务器，通过智能分块和检索使大型技术文档可供LLM访问。最初是为OpenAPI规范设计的，但现在支持包括markdown文档在内的通用知识管理。

概述

知识服务器解决了大型技术文档（OpenAPI规范、markdown文档等）的根本问题，这些文档无法放入LLM上下文窗口。它提供智能分块、语义搜索和自动参考解析，通过简单的界面提供完整、准确的信息。

主要特点

通用文档支持：OpenAPI规范（JSON/YAML）和markdown文档
智能分块：带有引用跟踪的上下文感知拆分
语义搜索：基于矢量的相似性搜索，具有可配置的嵌入模型
参考分辨率：自动扩展相关内容和依赖关系
研究代理：用于综合分析的智能ReAct代理
MCP集成：LLM工具的标准模型上下文协议服务器
可配置的LLM支持：本地模型（GGUF）和云提供商（AWS Bedrock）

快速开始

安装

# Clone and setup
git clone <repository-url>
cd knowledge-server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

配置

创建一个 .env 项目根目录中的文件：

# Required: Document directories
OPENAPI_SPECS_DIR=/path/to/your/openapi/specs

# Vector Store Configuration
VECTOR_STORE_DIR=./data/vectorstore
VECTOR_STORE_COLLECTION=knowledge_base
EMBEDDING_MODEL=dunzhang/stella_en_1.5B_v5
EMBEDDING_DEVICE=mps  # mps, cpu, cuda
MAX_TOKENS=8192

# API Index Configuration  
API_INDEX_PATH=./data/api_index.json

# Knowledge Retriever Configuration
RETRIEVAL_MAX_PRIMARY_RESULTS=5
RETRIEVAL_MAX_TOTAL_CHUNKS=15
RETRIEVAL_MAX_DEPTH=3
RETRIEVAL_TIMEOUT_MS=5000
CONTEXT_PRIORITIZE_PRIMARY=true

# MCP Server Configuration
MCP_SERVER_NAME=Knowledge Server
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8000

# Processing Configuration
SKIP_HIDDEN_FILES=true
SUPPORTED_EXTENSIONS=.json,.yaml,.yml
LOG_PROCESSING_PROGRESS=true

索引您的文档

# Index both OpenAPI specs and markdown documents
knowledge-server index

# Index only OpenAPI specifications
knowledge-server index --skip-markdown

# Index only markdown documents  
knowledge-server index --skip-openapi

# Specify custom markdown directory
knowledge-server index --markdown-dir /path/to/docs

# Control chunk size for markdown (default: 1000 tokens, max: 8000)
knowledge-server index --max-tokens 1500

启动MCP服务器

# Start the MCP server
knowledge-server serve

# With verbose output for debugging
knowledge-server serve -v

用法

作为MCP服务器

主要用例是作为MCP服务器，提供两个主要工具：

`search_api(query, max_response_length, max_chunks, include_references, max_depth)`

搜索你的索引知识库并返回相关块。

`research_api(question)`

使用智能ReAct代理进行全面分析和实施指导。

直接CLI使用

对于测试和开发：

# Ask questions about your documentation
knowledge-server ask "How do I authenticate with the user API?"

# Use the research agent for comprehensive analysis
knowledge-server research "What are the best practices for pagination in this API?"

# Advanced search options
knowledge-server ask "API rate limits" --max-chunks 30 --max-depth 2 --no-references

MCP客户端配置

重要：所有MCP配置都必须使用虚拟环境中的Python可执行文件(venv/bin/python)以确保所有依赖项都可用。

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "knowledge-server": {
      "command": "/path/to/knowledge-server/venv/bin/python",
      "args": [
        "-m", "src.mcp_server.server"
      ],
      "cwd": "/path/to/knowledge-server",
      "env": {
        "PYTHONPATH": "/path/to/knowledge-server"
      }
    }
  }
}

或者使用便利脚本（确保它是可执行的： chmod +x run_server.sh):

{
  "mcpServers": {
    "knowledge-server": {
      "command": "/path/to/knowledge-server/run_server.sh",
      "cwd": "/path/to/knowledge-server"
    }
  }
}

VS代码与Cline

添加到您的Cline MCP设置中：

{
  "mcpServers": {
    "knowledge-server": {
      "command": "/path/to/knowledge-server/venv/bin/python",
      "args": ["-m", "src.mcp_server.server"],
      "cwd": "/path/to/knowledge-server",
      "env": {
        "PYTHONPATH": "/path/to/knowledge-server"
      }
    }
  }
}

通用MCP客户端

服务器实现了标准的MCP协议，可以与任何兼容的客户端一起使用：

# Direct execution
cd /path/to/knowledge-server
source venv/bin/activate
python -m src.mcp_server.server

文档处理

OpenAPI规范

服务器处理OpenAPI 3.0/3.1规范：

支持格式：JSON和YAML
智能组块：按相关模式分组的操作
参考分辨率：自动$ref扩展
元数据抽取：全面的标记和分类

Markdown文档

支持结构化标记处理：

基于头部的分块：按可配置的令牌限制拆分部分
参考跟踪：跨文档链接和参考
导航楼：自动分段层次结构
内容分析：语义分类

建筑

知识服务器采用模块化架构：

文档处理者：处理OpenAPI和markdown解析
矢量存储管理器：ChromaDB与可配置嵌入的集成
知识检索器：两阶段检索，参考文献扩展
研究代理：基于LangGraph的智能分析
MCP服务器：LLM工具的标准协议接口

看建筑.md 获取详细的组件文档。

配置参考

环境变量

变量	描述	默认值
`OPENAPI_SPECS_DIR`	包含OpenAPI规范的目录	必填
`VECTOR_STORE_DIR`	矢量存储持久目录	`./data/vectorstore`
`VECTOR_STORE_COLLECTION`	矢量存储集合名称	`knowledge_base`
`EMBEDDING_MODEL`	句子转换模型	`dunzhang/stella_en_1.5B_v5`
`EMBEDDING_DEVICE`	嵌入装置	`mps`
`MAX_TOKENS`	每个区块的最大令牌数	`8192`
`API_INDEX_PATH`	API索引文件的路径	`./data/api_index.json`
`RETRIEVAL_MAX_PRIMARY_RESULTS`	最大主搜索结果	`5`
`RETRIEVAL_MAX_TOTAL_CHUNKS`	检索到的最大总块数	`15`
`RETRIEVAL_MAX_DEPTH`	最大参考膨胀深度	`3`
`RETRIEVAL_TIMEOUT_MS`	检索超时（毫秒）	`5000`
`MCP_SERVER_NAME`	MCP服务器显示名称	`Knowledge Server`
`MCP_SERVER_HOST`	MCP服务器主机	`localhost`
`MCP_SERVER_PORT`	MCP服务器端口	`8000`

嵌入模型

支持的嵌入模型（通过句子转换器）：

dunzhang/stella_en_1.5B_v5 （默认）-高质量的英语嵌入
sentence-transformers/all-MiniLM-L6-v2 -快速、轻便
sentence-transformers/all-mpnet-base-v2 -速度和质量的良好平衡
BAAI/bge-large-en-v1.5 -最先进的英语嵌入

设备支持

中央处理器：仅CPU处理（默认，最兼容）
猪支原体肺炎：Apple Silicon GPU加速（建议用于M1/M2/M3 Mac）
统一计算设备架构：NVIDIA GPU加速
自动：自动选择最佳可用设备

发展

测试

# Run all tests
source venv/bin/activate
python -m pytest tests/ -v

# Run specific test suites
python -m pytest tests/openapi_processor/ -v
python -m pytest tests/markdown_processor/ -v
python -m pytest tests/integration/ -v

代码质量

# Format and lint
source venv/bin/activate
black src/ tests/
isort src/ tests/
python -m pytest tests/

项目结构

knowledge-server/
├── src/
│   ├── cli/                    # Command-line interface
│   ├── mcp_server/            # MCP protocol server
│   ├── openapi_processor/     # OpenAPI document processing
│   ├── markdown_processor/    # Markdown document processing
│   ├── vector_store/          # ChromaDB integration
│   ├── retriever/            # Knowledge retrieval engine
│   ├── research_agent/       # Intelligent analysis agent
│   ├── llm/                  # LLM provider abstraction
│   └── utils/                # Shared utilities
├── tests/                    # Comprehensive test suite
├── data/                     # Generated indices and vector store
├── docs/                     # Documentation and specifications
└── samples/                  # Example documents and configurations

故障排除

常见问题

MCP服务器未启动

检查是否安装了所有依赖项： pip install -r requirements.txt
验证 .env 文件配置
确保配置中的目录存在并且可读

没有搜索结果

先运行索引： knowledge-server index
检查文档目录是否包含支持的文件
验证ChromaDB持久性目录是否可写

嵌入模型下载失败

检查互联网连接
尝试不同的嵌入模型
如果GPU内存不足，请使用CPU设备

LLM提供程序错误

验证Bedrock的AWS凭据和权限
检查本地提供程序的本地模型路径和GGUF格式
确保本地模型有足够的内存

性能优化

在可用的情况下使用GPU加速进行嵌入
调整 VECTOR_SEARCH_LIMIT 基于您的用例
考虑使用较小的嵌入模型以实现更快的索引
增加 max_chunks 用于全面但较慢搜索的参数

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

贡献

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

看 CLAUDE.md 用于开发指南和编码标准。