内容
# 🌟 MCP 内部 Wiki 服务器
<div align="center">
[](https://github.com/yourusername/mcp-internal-wiki)
[](LICENSE)
[](https://nodejs.org/)
<img src="https://raw.githubusercontent.com/microsoft/vscode-codicons/main/src/icons/book.svg" width="100" height="100" alt="MCP Wiki 图标">
**将您的内部知识直接连接到您的 IDE**
</div>
## 🔍 什么是 MCP Wiki Server？
MCP 内部 Wiki Server 是一个专门的桥梁，连接您公司的知识库和开发环境。通过使用模型上下文协议（Model Context Protocol，MCP），它可以在您需要的地方——您的编辑器中——**无缝访问文档**。
> 💡 **MCP**（模型上下文协议）是一个开放标准，用于将上下文信息集成到 AI 辅助开发环境中。
## ✨ 为什么使用 MCP Wiki Server？
### 🚀 提升生产力
- **即时知识获取**：无需在你的IDE和浏览器之间切换
- **一致的信息**：每个团队成员都能访问相同的最新文档
- **减少入职时间**：新开发者可以直接在他们的工作流程中找到信息
### 🔄 工作原理
```
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ │ │ │ │ │
│ Your Wiki │◄────┤ MCP Server │◄────┤ VS Code │
│ Sources │ │ │ │ Extension │
│ │ │ │ │ │
└────────────────┘ └────────────────┘ └────────────────┘
^ │
│ │
└──────────────────────────────────────────────┘
查询与响应流程
```
## 🎯 关键特性
- 📚 **多源集成**：同时连接多个维基平台
- 🔍 **上下文搜索**：通过高级查询功能精确找到所需内容
- 🚀 **代码转换**：将维基内容转换为多种语言的可执行代码
- 🏗️ **项目生成**：从文档生成完整的项目结构
- 🎨 **模板系统**：使用Handlebars模板进行一致的代码生成
- 🤖 **人工智能驱动**：利用AI提供商进行智能代码生成和转换
- 🧩 **可扩展架构**：为您的特定需求添加自定义源和适配器
- 🛠️ **平台无关**：与任何MCP兼容的编辑器兼容
- 🔒 **隐私优先**：所有内容保留在您的环境中；不进行外部API调用
- 🔐 **安全认证**：支持基本、令牌和自定义认证方法以适应私有维基
- ⚡ **闪电般快速**：通过多级缓存、连接池和批处理实现高级性能优化
- 🚀 **企业级规模**：智能资源管理和实时监控，处理数百万个维基页面
- 📊 **性能监控**：实时指标收集，包括缓存命中率、响应时间和吞吐量跟踪
## 📦 快速开始
```bash
```
# 全局安装
npm install -g mcp-internal-wiki
# 运行服务器
mcp-wiki-server
```
## 🔧 设置与配置
### 1. 安装
选择您喜欢的安装方法：
<details>
<summary>📥 <b>本地安装</b></summary>
<br>
```bash
# 克隆仓库
git clone https://github.com/yourusername/mcp-internal-wiki.git
cd mcp-internal-wiki
# 安装依赖
npm install
# 构建项目
npm run build
```
</details>
<details>
<summary>🌐 <b>全局安装</b></summary>
<br>
```bash
# 全局安装
npm install -g mcp-internal-wiki
# 运行服务器
mcp-wiki-server
```
</details>
<details>
<summary>⚡ <b>快速安装（无需安装）</b></summary>
<br>
```bash
npx mcp-internal-wiki
```
</details>
<details>
<summary>❄️ <b>NixOS 安装</b></summary>
<br>
```bash
# 通过 flake 安装
nix profile install github:yourusername/mcp-internal-wiki
# 或者不安装直接运行
nix run github:yourusername/mcp-internal-wiki
```
有关更多详细信息，请参见[NixOS安装指南](NIXOS_INSTALLATION.md)。
</details>
### 2. 配置 Wiki 源
创建或编辑 `mcp.config.json` 以包含您的 Wiki URL：
```json
{
"wikiUrls": [
"https://your-company-wiki.example.com",
"https://your-team-gitbook.example.io",
"https://private-confluence.example.com/wiki"
],
"cacheTimeoutMinutes": 30
}
```
### 3. 配置私有维基的身份验证
对于需要身份验证的维基，请在您的 `mcp.config.json` 中添加 `auth` 部分：
```json
{
"wikiUrls": [
"https://your-company-wiki.example.com",
"https://your-team-gitbook.example.io",
"https://private-confluence.example.com/wiki"
],
"cacheTimeoutMinutes": 30,
"auth": [
{
"urlPattern": "example\\.confluence\\.com",
"type": "basic",
"username": "username",
"password": "password",
"comment": "请替换为您 Confluence 实例的实际凭据"
},
{
"urlPattern": "example\\.sharepoint\\.com",
"type": "token",
"token": "your-access-token",
"comment": "请替换为您 SharePoint 实例的实际令牌"
},
{
"urlPattern": "api\\.github\\.com",
"type": "custom",
"headerName": "Authorization",
"headerValue": "token ghp_yourgithubpersonalaccesstoken",
"comment": "用于访问私有 GitHub 仓库"
}
]
}
```
支持的身份验证类型：
- `basic`: 用于 HTTP Basic Auth 的用户名和密码
- `token`: Bearer 令牌身份验证
- `custom`: 自定义头部身份验证
- `oauth`: OAuth 2.0 身份验证（高级配置）
### 4. VS Code 集成
要在 VS Code 中使用 MCP Internal Wiki Server：
1. **安装 Copilot MCP 扩展**: [市场链接](https://marketplace.visualstudio.com/items?itemName=automatalabs.copilot-mcp)
2. **配置 MCP 服务器**：
- 在工作区根目录下创建 `.vscode/mcp.json`：
```jsonc
{
"servers": {
"my-mcp-wiki-server": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/server.js"],
"env": {
"MCP_CONFIG_PATH": "${workspaceFolder}/mcp.config.json"
}
}
}
}
```
- 对于全局安装，使用 `"command": "mcp-wiki-server"`。
- 对于 npx，使用 `"command": "npx", "args": ["mcp-internal-wiki"]`。
3. **重启 VS Code** 以应用配置。
4. **测试集成**：
- 打开一个 markdown 文件并输入与您的 wiki 内容相关的查询。
- MCP 扩展应提供来自您 wiki 源的补全或上下文。
5. **故障排除**：
- 检查 VS Code 输出面板（MCP 通道）以获取日志。
- 确保 MCP 服务器正在运行，并且 `mcp.config.json` 是有效的。
- 请参阅 `TESTING_VS_CODE.md` 和 `VSCODE_QUICK_REFERENCE.md` 以获取更多帮助。
## VS Code 集成与测试
### 设置
1. 从 VS Code Marketplace 安装 Copilot MCP 扩展。
2. 在你的工作区根目录下创建 `.vscode/mcp.json`：
```jsonc
{
"servers": {
"my-mcp-wiki-server": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/server.js"],
"env": {
"MCP_CONFIG_PATH": "${workspaceFolder}/mcp.config.json"
}
}
}
}
```
- 对于全局安装，使用 `"command": "mcp-wiki-server"`。
- 对于 npx，使用 `"command": "npx", "args": ["mcp-internal-wiki"]`。
3. 重启 VS Code 以应用配置。
### 测试
- 打开一个markdown文件，并输入与您的wiki内容相关的查询。
- MCP扩展应该提供来自您的wiki源的补全或上下文。
- 运行 `npm run test:simple` 或 `npm run test:interactive` 进行命令行验证。
### 故障排除
- 检查 VS Code 输出面板（MCP 通道）中的日志。
- 确保 MCP 服务器正在运行，并且 `mcp.config.json` 是有效的。
- 请参阅 `TESTING_VS_CODE.md` 和 `VSCODE_QUICK_REFERENCE.md` 以获取更多帮助。
## 🚀 内容转换与代码生成
MCP Internal Wiki Server 包含强大的转换功能，可以将您的 wiki 文档转换为可执行代码和完整的项目结构。
### 可用的 MCP 工具
服务器通过标准 MCP 协议提供这些转换工具：
#### 🔄 `transform_content`
将wiki内容或markdown转换为任何编程语言中的可执行代码。
**在VS Code中的使用：**
- 在编辑器中选择wiki内容
- 通过MCP工具界面访问
- 选择目标语言和框架
**参数：**
- `content`: 要转换的wiki内容或markdown
- `targetLanguage`: 目标编程语言（typescript、python、javascript等）
- `framework`: 可选框架（express、fastapi、react等）
- `projectType`: 可选项目类型（api、library、cli等）
#### 🏗️ `generate_code`
根据维基内容使用模板和人工智能驱动的生成来生成代码。
**参数：**
- `content`: 用于生成代码的维基文档
- `codeType`: 要生成的代码类型（dockerfile、typescript、python、yaml等）
- `templateName`: 可选的模板名称（express-server、typescript-class等）
**功能：**
- **基于模板的生成**：使用Handlebars模板以确保输出的一致性
- **增强的人工智能**：利用配置的人工智能提供者进行智能代码生成
- **多格式支持**：生成Dockerfile、package.json、TypeScript类等
#### 📁 `generate_project`
从维基文档生成完整的项目结构。
**参数：**
- `content`: 描述项目需求的维基内容
- `projectType`: 项目类型 (express-api, react-app, cli-tool 等)
- `language`: 编程语言 (typescript, python, javascript 等)
**功能：**
- **完整的项目搭建**: 创建完整的目录结构
- **多文件生成**: 生成所有必要的项目文件
- **最佳实践**: 遵循既定的模式和约定
### 模板系统
转换系统使用 Handlebars 模板进行一致的代码生成：
**可用模板：**
- `typescript-class.hbs` - TypeScript 类定义
- `express-server.hbs` - Express.js 服务器设置
- `dockerfile.hbs` - Docker 容器化
- `package-json.hbs` - Node.js 包配置
- `readme.hbs` - 项目文档
**自定义模板：**
使用 Handlebars 语法在 `/templates` 目录中添加您自己的模板。
### AI集成
该转换系统与多个AI提供商集成：
- **OpenAI GPT-4o**：先进的代码生成和分析
- **Google Gemini 2.5 Pro**：智能内容转换
- **Azure OpenAI**：企业级AI能力
- **Claude**：Anthropic的AI，用于精确的代码生成
**在 `mcp.config.json` 中的配置：**
```json
{
"ai": {
"enabled": true,
"providers": {
"openai": {
"apiKey": "your-openai-api-key",
"model": "gpt-4o"
},
"gemini": {
"apiKey": "your-gemini-api-key",
"model": "gemini-2.5-pro"
}
},
"primaryProvider": "openai"
}
}
```
### 示例转换工作流
#### 1. API 文档 → Express 服务器
```markdown
```
# 用户认证 API
创建一个带有 JWT 认证的 REST API
- POST /auth/login
- POST /auth/register
- GET /auth/profile
```
↓ **transform_content** with `targetLanguage: "typescript"` and `framework: "express"`
```typescript
// 生成的带有 JWT 认证的 Express.js 服务器
import express from 'express';
import jwt from 'jsonwebtoken';
// ... 完整实现
```
#### 2. 部署指南 → Docker 配置
```markdown
```
# 部署要求
- Node.js 18 运行时
- PostgreSQL 数据库
- Redis 用于缓存
- 环境变量用于配置
```
↓ **generate_code** 使用 `codeType: "dockerfile"`
```dockerfile
FROM node:18-alpine
RUN apk add --no-cache postgresql-client redis
```
# ... 完成 Docker 配置
```
#### 3. 项目规范 → 完整脚手架
```markdown
```
# CLI工具要求
基于TypeScript的命令行工具用于文件处理
- 文件输入/输出操作
- 通过CLI参数进行配置
- 使用Jest进行单元测试
```
↓ **generate_project** 使用 `projectType: "cli-tool"` 和 `language: "typescript"`
```
project/
├── src/
│ ├── cli.ts
│ ├── processor.ts
│ └── config.ts
├── tests/
├── package.json
├── tsconfig.json
└── README.md
```
### 测试转换功能
测试转换能力：
```bash
```
# 运行转换测试
npm run test:transform
# 测试单个转换方法
node tests/test-mcp-tools.js
```
## 🧩 代理架构
MCP Internal Wiki Server 现在使用模块化的基于代理的架构来支持所有核心功能：
- **WikiContentAgent**: 获取并过滤查询的维基内容
- **AIRelevanceAgent**: 使用 AI 提供者对内容相关性进行评分
- **WikiIndexAgent**: 管理（重新）构建维基搜索索引
### 如何使用代理
- 使用 `src/agents/index.ts` 中的代理管理器来访问和协调代理
- 通过 `just agent-test` 或 Nix shell 运行基于代理的测试
- 代理端点在 Docker POC 中可用于集成测试
有关代理的完整使用和开发指南，请参见 [COPILOT_INSTRUCTIONS.md](.github/COPILOT_INSTRUCTIONS.md)。
## 🏗️ 使用案例
- **开发者文档**：即时访问API参考、代码标准和设计模式
- **入职培训**：帮助新团队成员在不离开其IDE的情况下找到信息
- **知识管理**：创建一个统一的界面以整合分散的知识库
- **DevOps实践**：快速参考基础设施模式和操作程序
## ⚡ 性能与可扩展性
### 企业级性能优化
MCP Wiki Server 包含用于处理大规模部署的高级性能优化功能：
- **🚀 多级缓存**：智能缓存管理与自动分配：
- 内容缓存（60% 的内存）用于大型维基页面
- 元数据缓存（30% 的内存）用于页面信息
- 查询缓存（10% 的内存）用于搜索结果
- LRU（最近最少使用）驱逐，具有可配置的大小和项目限制
- **🔍 全文搜索索引**：实时搜索能力：
- 背景索引重建，性能影响最小
- 模糊搜索匹配，支持拼写错误和部分查询
- 内存优化的倒排索引结构
- 可配置的索引间隔
- **⚡ 基于优先级的批处理**：后台作业管理：
- 可配置的并发限制，以优化资源使用
- 自动重试机制，采用指数退避
- 优先级队列，用于关键任务与后台任务
- 作业去重，防止冗余处理
- **🔄 HTTP 连接池**：高效的网络资源管理：
- 连接重用以减少开销
- 自动故障转移和健康监控
- 可配置的池大小和超时设置
- 资源清理和垃圾回收
- **📊 实时性能监控**：全面的指标收集：
- 缓存命中率和内存使用情况跟踪
- 响应时间监控，检测慢查询
- 请求吞吐量和错误率跟踪
- 性能仪表板和警报系统
### 性能测试
运行全面的性能测试以验证您的部署：
```bash
```
# 测试缓存性能（即时 - 无需构建）
npm run test:cache
# 完整性能测试套件（需要构建）
npm run build && npm run test:performance
# 并发用户的负载测试
npm run test:load
# 性能 CLI 工具
npm run perf benchmark
npm run perf monitor
```
### 大规模部署的配置
在您的 `mcp.config.json` 中配置性能设置：
```json
{
"performance": {
"cache": {
"maxSize": 500, // 500MB 缓存大小
"ttl": 3600000, // 1 小时 TTL
"maxItems": 50000, // 最多 50k 项
"enablePersistence": true
},
"indexing": {
"enabled": true,
"rebuildInterval": 300000, // 5 分钟
"backgroundSync": true
},
"batch": {
"batchSize": 20,
"concurrency": 10,
"maxRetries": 3
},
"pool": {
"maxConnections": 50,
"acquireTimeout": 10000,
"idleTimeout": 60000
}
}
}
```
### 扩展指南
| 规模 | 页面 | 用户 | 缓存大小 | 预期性能 |
|----------|-----------|-----------|----------|----------------|
| 小型 | < 10K | < 10 | 100MB | > 50 RPS |
| 中型 | < 100K | < 50 | 500MB | > 100 RPS |
| 大型 | < 1M | < 200 | 2GB | > 200 RPS |
| 企业级 | > 1M | > 500 | 8GB | > 500 RPS |
## 🧪 测试
### 标准测试命令
**Node.js 测试**
```bash
```
# 构建项目
npm run build
# 或者
直接构建
# 运行简单测试
npm run test:simple
# 或者
直接测试简单
# 运行交互式测试客户端
npm run test:interactive
# 或者
直接使用 test-interactive
# 运行查询测试
npm run test:query
# 或
仅测试查询
# 运行所有测试
npm run test:all
# 或者
直接使用 test-all
```
**Nix 测试**
```bash
# 使用 Nix 的简单测试
nix run .#test
# 或者
直接使用 nix-test
# 使用 Nix 进行交互式测试
nix run .#interactive
# 或者
直接使用 nix-test-interactive
# 使用 Nix 构建
nix build
# 或者
直接使用 nix-build
```
### 🐳 Docker 测试 (POC 私有 Wiki)
该项目包括一个全面的基于 Docker 的 POC，用于测试私有 Wiki 身份验证：
**Docker POC 命令**
```bash
# 构建POC Docker镜像（包括TypeScript编译）
just docker-poc-build
# 构建不使用缓存的POC Docker镜像（用于全新构建）
just docker-poc-build-no-cache
# 启动POC容器（markdown服务器 + MCP服务器）
just docker-poc-up
# 停止POC容器
只需运行 `docker-poc-down`
# 运行全面的POC测试套件
just docker-poc-test
# 单个POC测试
just test-auth-poc # 基本认证测试
just test-auth-integration # 集成认证测试
just test-poc-interactive # 交互式测试客户端
just test-poc-monitor # 容器健康监控
just test-poc-menu # 交互式测试菜单
```
**Docker POC演示的内容：**
- ✅ **私有维基认证**：MCP服务器连接到受密码保护的维基
- ✅ **容器化部署**：两个服务在Docker容器中运行，并进行健康检查
- ✅ **认证方法**：基本认证、令牌认证和自定义头部认证
- ✅ **集成测试**：全面的测试套件验证所有功能
- ✅ **生产就绪**：具有网络和服务发现的真实部署场景
## 🏗️ 架构
- **📡 Stdio/JSON-RPC 通信**: 轻量级、快速的通信协议
- **🧠 MCPServer 核心**: 中央请求处理器和方法调度器
- **🔌 可扩展源**: 针对不同维基平台的可插拔系统
- **🔍 智能上下文检索**: 优化的搜索和上下文管理
## 📚 文档
- [完整安装指南](INSTALLATION.md)
- [Linux 安装指南](LINUX_INSTALLATION.md)
- [NixOS 安装指南](NIXOS_INSTALLATION.md)
- [VS Code 集成指南](SETUP_VSCODE.md)
- [VS Code 测试指南](TESTING_VS_CODE.md)
- [VS Code 配置示例](examples/)
- [性能测试指南](docs/PERFORMANCE.md)
- [性能优化文档](docs/TESTING-PERFORMANCE.md)
- [Nix 开发指南](NIX_DEVELOPMENT.md)
- [项目计划](PROJECT_PLAN.md)
- [Wiki 集成指南](docs/WIKI_INTEGRATION.md)
## 🔧 扩展
MCP Wiki Server 被设计为可扩展的：
- 在 `src/sources/` 中添加新的源，并在 `MCPServer` 中注册它们
- 根据需要在 `MCPServer` 中实现新的 MCP 方法
- 支持多种维基格式：
- Markdown
- MediaWiki
- Gitbook
- Confluence
- SharePoint
- 自定义源
## 👨💻 开发
```bash
```
# 使用 Nix 进入开发环境
nix develop
# 或者
直接使用 nix-shell
# 使用 Nix 构建
nix build
# 或者
直接使用 nix-build
```
有关更多详细信息，请参阅 [Nix Development Guide](NIX_DEVELOPMENT.md)。
## 📋 需求
- Node.js 14.x 或更高版本
- 对于 NixOS：启用 Flakes
## 📄 许可证
[MIT](LICENSE) - 随意使用、修改和分发此软件。
---
<div align="center">
为重视工作流程的开发者们倾心制作 ❤️
</div>
MCP 市场
