星光MCP演示
使用MCP(模型上下文协议)从多个来源生成文档的演示。
🚀 快速启动
1.安装依赖项```bash
npm install
cd mcp-server && npm install && cd ..
cd petstore-mcp-server && npm install && cd ..
cd mcp-client && npm install && cd ..
### 2.测试工作流程```bash
# Test all components
npm run test-workflow
# Run the complete demo
npm run demo
# View the documentation
npm run dev
📋 这个演示显示了什么
该项目演示了从多个来源自动生成文档的完整MCP工作流程。
🏗️ 建筑```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Starlight │ │ MCP Client │ │ Pet Store │
│ Docs Site │◄───┤ (Orchestrator) │◄───┤ MCP Server │
│ │ │ │ │ │
│ - Guides │ │ - Connects to │ │ - OpenAPI Spec │
│ - Reference │ │ multiple MCP │ │ - API Endpoints │
│ - API Docs │ │ servers │ │ - Data Schemas │
│ - Generated │ │ - Generates docs │ │ - Examples │
└─────────────────┘ └──────────────────┘ └─────────────────┘
## 🔧 MCP客户端/服务器架构
该项目展示了一个完整的 **模型上下文协议(MCP)** 自动化文档生成的工作流程。它由三个主要部分组成:
### 🎯 **MCP客户端** (`mcp-client/client.js`)
这 **星光MCP客户端** 充当连接到多个MCP服务器并协调文档生成的编排器:
**主要特点:**
- **多服务器连接**:可以同时连接到多个MCP服务器
- **工具执行**:调用远程服务器上的工具并处理响应
- **资源管理**:从连接的服务器读取并列出资源
- **文档生成**:自动从多个来源生成组合文档
- **文件系统集成**:将生成的文档写入星光文档结构
**主要方法:**
- `connectToServer()` -建立与MCP服务器的连接
- `generateApiDocs()` -从宠物商店服务器生成API文档
- `generateStarlightDocs()` -检索现有的星光文档结构
- `generateCombinedDocs()` -结合多个来源创建统一的文档
### 🏪 **宠物店MCP服务器** (`petstore-mcp-server/server.js`)
此服务器提供基于OpenAPI规范的API文档工具:
**可用工具:**
- `get_api_specification` -返回完整的OpenAPI规范
- `list_endpoints` -列出所有API终结点(可按标记筛选)
- `get_endpoint_details` -获取有关特定终结点的详细信息
- `get_schemas` -检索数据模型和模式
- `generate_markdown_docs` -生成格式化的markdown文档
- `get_api_info` -返回基本的API元数据
**关键能力:**
- **OpenAPI集成**:阅读自 `petstore-api.json` 规格
- **灵活的输出**:支持不同的文档格式(完整、端点、模式、概述)
- **示例生成**:包括请求/响应示例
- **资源访问**:提供对原始API规范文件的访问
### 📚 **星光MCP服务器** (`mcp-server/server.js`)
此服务器管理现有的星光文档,并提供内容发现工具:
**可用工具:**
- `list_docs` -列出所有文档页面(可按类别筛选)
- `search_docs` -按关键字搜索文档内容
- `get_doc_content` -使用frontmatter检索特定页面内容
- `get_site_structure` -返回完整的网站导航结构
**关键能力:**
- **内容发现**:扫描 `src/content/docs/` 目录
- **前端处理**:从markdown文件中提取元数据
- **搜索功能**:跨文档的全文搜索
- **结构分析**:提供网站导航和组织
- **资源访问**:列出并读取文档文件
### 🔄 **工作流过程**
典型的工作流程遵循以下模式:
1. **客户端初始化**:MCP客户端启动并准备连接到服务器
1. **服务器连接**:客户端连接到宠物店和星光MCP服务器
1. **内容检索**:
- 宠物商店服务器提供OpenAPI规范中的API文档
- 星光服务器提供现有的文档结构
1. **文档生成**:客户端组合内容并生成统一的文档
1. **文件输出**:生成的文档将写入 `src/content/docs/`
1. **清理**:客户端与所有服务器断开连接
### 🏗️ **架构优势**
- **模块化设计**:每个服务器都有特定的职责
- **可扩展**:易于为不同的内容源添加新的MCP服务器
- **自动化**:文档生成可以集成到CI/CD管道中
- **基于标准的**:使用官方MCP SDK和协议
- **内容感知**:了解API规范和现有文档
## 🧞 可用命令
|命令|操作|
| :------------------------ | :----------------------------------------------- |
| `npm install` |安装依赖项|
| `npm run dev` |在以下位置启动本地开发服务器 `localhost:4321` |
| `npm run build` |构建您的生产站点(包括文档生成)|
| `npm run preview` |在部署之前,在本地预览您的构建|
| `npm run demo` |运行完整的MCP工作流演示|
| `npm run test-workflow` |测试所有MCP组件|
| `npm run generate-docs` |从MCP服务器生成文档|
| `npm run demo-petstore` |仅测试宠物店MCP服务器|
| `npm run demo-starlight` |仅测试星光MCP服务器|
## 📁 项目结构```
.
├── mcp-server/ # Starlight MCP server
├── petstore-mcp-server/ # Pet Store API MCP server
├── mcp-client/ # MCP client orchestrator
├── src/content/docs/ # Generated documentation
├── test-workflow.js # Workflow test script
└── MCP-DEMO-WORKFLOW.md # Detailed documentation
🔍 生成的文档
运行演示后,您会发现:
- API文档:
src/content/docs/api/petstore-api.md - 更新索引:
src/content/docs/index.mdx
📚 了解更多
- MCP演示工作流程指南 -详细文件
- 星光文件
- 模型上下文协议
👀 想了解更多吗?
结账 星光的文档,阅读 Astro文件,或跳进 Astro Discord 服务器.
