@creatoria/miniapp-mcp 0.1.0

package/docs/tasks.B1.atomize.md

@@ -0,0 +1,352 @@
+# Task Card: [B1] MCP Server 骨架
+
+**Task ID**: B1
+**Task Name**: MCP Server 骨架实现
+**Charter**: `docs/charter.B1.align.yaml`
+**Stage**: B (Core Architecture)
+**Status**: ✅ COMPLETED (Retrospective)
+**Estimated**: 2-3 hours
+**Actual**: ~2 hours
+**Completed**: 2025-10-02
+
+---
+
+## 目标 (Goal)
+
+实现可运行的 MCP Server 入口，支持 stdio transport 连接，为后续工具注册提供基础框架。
+
+**交付物**:
+- ✅ `src/server.ts` (64 lines)
+- ✅ `startServer(config)` 函数
+- ✅ ListToolsRequestSchema 处理器
+- ✅ 优雅关闭机制
+
+---
+
+## 前置条件 (Prerequisites)
+
+- ✅ A3: 仓库结构已初始化
+- ✅ `@modelcontextprotocol/sdk` 已安装 (v0.x.x)
+- ✅ TypeScript 配置完成 (tsconfig.json)
+- ✅ 了解 MCP 协议基础
+
+---
+
+## 实现步骤 (Steps)
+
+### 1. 创建 Server 入口文件 ✅
+
+**文件**: `src/server.ts`
+
+**步骤**:
+```typescript
+// 导入 MCP SDK
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+
+// 定义 startServer 函数
+export async function startServer(config: ServerConfig = {}) {
+  // 实现...
+}
+```
+
+**验证**: TypeScript 编译通过，无导入错误
+
+---
+
+### 2. 实例化 Server 对象 ✅
+
+**代码**:
+```typescript
+const server = new Server(
+  {
+    name: 'creatoria-miniapp-mcp',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+)
+```
+
+**验证**: Server 对象创建成功
+
+---
+
+### 3. 集成 SessionStore ✅
+
+**代码**:
+```typescript
+import { SessionStore } from './core/session.js'
+
+const { capabilities = ['core'], outputDir, sessionTimeout } = config
+
+const sessionStore = new SessionStore({
+  outputDir,
+  sessionTimeout,
+})
+```
+
+**验证**: SessionStore 正确接收配置
+
+---
+
+### 4. 注册工具 ✅
+
+**代码**:
+```typescript
+import { registerTools } from './tools/index.js'
+
+const tools = registerTools(server, {
+  capabilities,
+  getSession: (sessionId) => {
+    const session = sessionStore.getOrCreate(sessionId)
+    sessionStore.updateActivity(sessionId)
+    return session
+  },
+  deleteSession: (sessionId) => sessionStore.delete(sessionId),
+})
+```
+
+**验证**: tools 数组包含注册的工具
+
+---
+
+### 5. 实现 ListToolsRequestSchema 处理器 ✅
+
+**代码**:
+```typescript
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools }
+})
+```
+
+**验证**: `list_tools` 请求返回正确工具列表
+
+---
+
+### 6. 配置 Transport 并连接 ✅
+
+**代码**:
+```typescript
+const transport = new StdioServerTransport()
+await server.connect(transport)
+
+console.error('WeChat Mini Program MCP Server running on stdio')
+console.error(`Capabilities: ${capabilities.join(', ')}`)
+console.error(`Tools registered: ${tools.length}`)
+```
+
+**验证**:
+- 日志输出到 stderr
+- Server 成功监听 stdin/stdout
+
+---
+
+### 7. 实现优雅关闭 ✅
+
+**代码**:
+```typescript
+const cleanup = () => {
+  console.error('\nShutting down MCP server...')
+  sessionStore.dispose()
+  process.exit(0)
+}
+
+process.on('SIGINT', cleanup)
+process.on('SIGTERM', cleanup)
+```
+
+**验证**:
+- CTRL+C 触发 cleanup
+- sessionStore.dispose() 被调用
+- 进程正常退出
+
+---
+
+## 完成标准 (Definition of Done)
+
+### 功能完成 ✅
+
+- [x] `node dist/server.js` 可启动 Server
+- [x] MCP 客户端可连接
+- [x] `list_tools` 返回工具列表
+- [x] SIGINT/SIGTERM 触发优雅关闭
+- [x] sessionStore.dispose() 正确调用
+
+### 代码质量 ✅
+
+- [x] TypeScript 编译 0 错误
+- [x] 无 ESLint 错误
+- [x] 代码行数 <100 行 (实际 64 行)
+- [x] JSDoc 注释完整
+- [x] 符合 ESM 规范（.js 后缀）
+
+### 测试 ✅
+
+- [x] 手动测试：启动并连接成功
+- [x] 集成测试：通过工具测试间接验证
+- [x] 优雅关闭测试：CTRL+C 正常退出
+
+### 文档 ⏳
+
+- [x] 代码注释完整
+- [x] README 更新（启动说明）
+- [x] types.ts 定义 ServerConfig
+- ⏳ charter.B1.align.yaml (追溯)
+- ⏳ tasks.B1.atomize.md (本文档)
+
+---
+
+## 实现结果 (Implementation)
+
+### 文件清单
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `src/server.ts` | 64 | Server 入口和配置 |
+| `src/types.ts` | +10 | ServerConfig 接口 |
+
+### 关键代码片段
+
+**ServerConfig 接口**:
+```typescript
+export interface ServerConfig {
+  capabilities?: string[]
+  outputDir?: string
+  sessionTimeout?: number
+}
+```
+
+**startServer 函数签名**:
+```typescript
+export async function startServer(config: ServerConfig = {}): Promise<void>
+```
+
+### 设计决策
+
+1. **函数式 API**
+   - 使用 `startServer()` 函数而非类封装
+   - 理由：简化使用，便于测试
+
+2. **依赖注入**
+   - SessionStore 和 registerTools 通过参数传入
+   - 理由：解耦，提高可测试性
+
+3. **stderr 日志**
+   - 所有日志输出到 console.error
+   - 理由：避免干扰 stdio transport
+
+4. **优雅关闭**
+   - 监听 SIGINT/SIGTERM
+   - 理由：确保资源释放（SessionStore.dispose）
+
+---
+
+## 测试证据 (Test Evidence)
+
+### 手动测试
+
+**启动 Server**:
+```bash
+$ node dist/server.js
+WeChat Mini Program MCP Server running on stdio
+Capabilities: core
+Tools registered: 4
+```
+
+**MCP 客户端连接**:
+```bash
+# 使用 MCP Inspector 或 Claude Desktop 连接
+# 验证 list_tools 返回正确工具列表
+```
+
+**优雅关闭**:
+```bash
+$ node dist/server.js
+^C
+Shutting down MCP server...
+Session 12345 cleaned up successfully
+```
+
+### 集成测试
+
+通过后续 C1-C5 工具测试间接验证：
+- ✅ Server 可正常启动
+- ✅ 工具调用成功
+- ✅ SessionStore 正常工作
+
+---
+
+## 已知问题 (Known Issues)
+
+### 技术债务
+
+1. **无单元测试** - 🟡 中优先级
+   - 原因：Server 入口代码难以单独测试
+   - 影响：依赖集成测试验证
+   - 计划：Stage G 补充集成测试
+
+2. **仅支持 stdio** - 🟢 低优先级
+   - 原因：当前需求仅 stdio
+   - 影响：无法通过 HTTP/WebSocket 连接
+   - 计划：未来扩展 transport
+
+### 风险
+
+1. **MCP SDK 升级** - 🟢 低风险
+   - 缓解：锁定 SDK 版本
+   - 监控：定期检查 SDK 更新
+
+---
+
+## 参考资料 (References)
+
+### 文档
+
+- `docs/完整实现方案.md` - Server 架构设计
+- `docs/第一版本方案.md` - MCP 集成方案
+- `docs/charter.B1.align.yaml` - 任务对齐文档
+
+### 代码
+
+- `src/core/session.ts` - SessionStore 实现（B2）
+- `src/tools/index.ts` - registerTools 函数（C5）
+
+### 外部资源
+
+- [MCP SDK 文档](https://github.com/anthropics/modelcontextprotocol)
+- [MCP 协议规范](https://spec.modelcontextprotocol.io)
+
+---
+
+## 后续任务 (Next Steps)
+
+### 依赖此任务的后续任务
+
+- ✅ B2: SessionStore 实现（已完成）
+- ✅ C5: registerTools 实现（已完成）
+- ⏳ E3: CLI 集成（未开始）
+
+### 改进建议
+
+1. **性能优化**
+   - 添加启动时间监控
+   - 优化 SessionStore 初始化
+
+2. **可观测性**
+   - 集成结构化日志
+   - 添加性能指标
+
+3. **扩展性**
+   - 支持多种 transport
+   - 支持配置热重载
+
+---
+
+**任务状态**: ✅ COMPLETED
+**代码提交**: ✅ 已提交（随 A2-B1-B2 修复）
+**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)