@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/mcp/server-guide.md

@@ -0,0 +1,300 @@
+# MCP Server Guide
+
+## Creating a Custom MCP Server
+
+### Minimal Server
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'my-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'my_tool',
+      description: 'Does something useful',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          input: { type: 'string' }
+        },
+        required: ['input']
+      }
+    }
+  ]
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === 'my_tool') {
+    return {
+      content: [{ type: 'text', text: 'Result' }]
+    };
+  }
+  throw new Error('Unknown tool');
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### Tool Definition Pattern
+
+```typescript
+interface ToolDef {
+  name: string;
+  description: string;
+  schema: z.ZodObject<any>;
+  handler: (args: any) => Promise<{ content: Array<{ type: 'text'; text: string }> }>;
+}
+
+const tools: ToolDef[] = [
+  {
+    name: 'example_tool',
+    description: 'Example tool',
+    schema: z.object({
+      input: z.string().describe('Input text')
+    }),
+    handler: async (args) => ({
+      content: [{ type: 'text', text: `Processed: ${args.input}` }]
+    })
+  }
+];
+```
+
+### Schema Conversion
+
+Convert Zod to JSON Schema for MCP:
+
+```typescript
+function zodToJsonSchema(schema: z.ZodObject<any>) {
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+
+  for (const [key, value] of Object.entries(schema.shape)) {
+    properties[key] = zodTypeToJsonSchema(value);
+    if (!value.isOptional()) required.push(key);
+  }
+
+  return { type: 'object', properties, required };
+}
+```
+
+## Deployment
+
+### Local Development
+
+```bash
+# Build server
+npm run build
+
+# Test manually
+node dist/my-server.js
+```
+
+### Claude Code Integration
+
+Add to `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["/absolute/path/to/dist/my-server.js"],
+      "env": {
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+### NPM Package
+
+```json
+{
+  "name": "my-mcp-server",
+  "bin": {
+    "my-server": "dist/server.js"
+  },
+  "files": ["dist"]
+}
+```
+
+Users install via:
+```bash
+npm install -g my-mcp-server
+```
+
+Config:
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "my-server"
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Error Handling
+
+```typescript
+handler: async (args) => {
+  try {
+    const result = await doWork(args);
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ error: error.message })
+      }],
+      isError: true
+    };
+  }
+}
+```
+
+### Logging
+
+```typescript
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+
+function log(level: string, message: string) {
+  if (shouldLog(level)) {
+    console.error(`[${level}] ${message}`);
+  }
+}
+```
+
+### Validation
+
+```typescript
+import { z } from 'zod';
+
+const schema = z.object({
+  file: z.string().min(1),
+  line: z.number().int().positive()
+});
+
+handler: async (args) => {
+  const validated = schema.parse(args);
+  // Use validated data
+}
+```
+
+### Timeouts
+
+```typescript
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Timeout')), ms)
+  );
+  return Promise.race([promise, timeout]);
+}
+
+handler: async (args) => {
+  return await withTimeout(doWork(args), 30000);
+}
+```
+
+## Examples
+
+### File System Tool
+
+```typescript
+{
+  name: 'read_file',
+  description: 'Read file contents',
+  schema: z.object({
+    path: z.string().describe('File path')
+  }),
+  handler: async ({ path }) => {
+    const content = await fs.readFile(path, 'utf-8');
+    return { content: [{ type: 'text', text: content }] };
+  }
+}
+```
+
+### HTTP API Tool
+
+```typescript
+{
+  name: 'fetch_data',
+  description: 'Fetch from API',
+  schema: z.object({
+    url: z.string().url()
+  }),
+  handler: async ({ url }) => {
+    const response = await fetch(url);
+    const data = await response.json();
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+  }
+}
+```
+
+### Database Tool
+
+```typescript
+{
+  name: 'query_db',
+  description: 'Execute SQL query',
+  schema: z.object({
+    query: z.string(),
+    params: z.array(z.any()).optional()
+  }),
+  handler: async ({ query, params = [] }) => {
+    const rows = await db.query(query, params);
+    return { content: [{ type: 'text', text: JSON.stringify(rows) }] };
+  }
+}
+```
+
+## Testing
+
+### Unit Tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('my_tool', () => {
+  it('processes input correctly', async () => {
+    const result = await handler({ input: 'test' });
+    expect(result.content[0].text).toContain('test');
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+import { spawn } from 'child_process';
+
+it('server responds to list_tools', async () => {
+  const server = spawn('node', ['dist/server.js']);
+
+  server.stdin.write(JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/list'
+  }) + '\n');
+
+  const response = await readResponse(server.stdout);
+  expect(response.result.tools).toHaveLength(1);
+});
+```
+
+## Next Steps
+
+- [Client Guide](./client-guide.md) - Use tools in agents
+- [Configuration](./configuration.md) - Environment variables
+- [Performance](./performance.md) - Optimization tips

package/docs/mcp-compatibility-matrix.md

@@ -0,0 +1,52 @@
+# MCP Server Compatibility Matrix
+
+## Namespace Format
+
+All community MCP server tools use the format: `mcp__servername__toolname`
+
+## Supported Community Servers
+
+### Filesystem Server
+- **Package**: `@modelcontextprotocol/server-filesystem`
+- **Namespace**: `mcp__filesystem__*`
+- **Tools**:
+  - `mcp__filesystem__read_file`
+  - `mcp__filesystem__write_file`
+  - `mcp__filesystem__list_directory`
+  - `mcp__filesystem__create_directory`
+  - `mcp__filesystem__move_file`
+  - `mcp__filesystem__get_file_info`
+
+### GitHub Server
+- **Package**: `@modelcontextprotocol/server-github`
+- **Namespace**: `mcp__github__*`
+- **Tools**:
+  - `mcp__github__create_issue`
+  - `mcp__github__create_pull_request`
+  - `mcp__github__search_repositories`
+  - `mcp__github__get_file_contents`
+
+### Slack Server
+- **Package**: `@modelcontextprotocol/server-slack`
+- **Namespace**: `mcp__slack__*`
+- **Tools**:
+  - `mcp__slack__send_message`
+  - `mcp__slack__list_channels`
+  - `mcp__slack__read_channel`
+
+## Internal Tools (No Namespace)
+
+Internal OMC tools do not use namespace prefixes:
+- `lsp_*` - Language Server Protocol tools
+- `ast_grep_*` - AST manipulation tools
+- `state_*` - State management tools
+- `notepad_*` - Notepad tools
+- `project_memory_*` - Memory tools
+- `python_repl` - Python REPL
+- `trace_*` - Trace tools
+
+## Backward Compatibility
+
+The resolver supports both formats:
+- Namespaced: `mcp__filesystem__read_file` → resolves to tool
+- Plain: `read_file` → resolves to internal tool

package/docs/plans/2026-03-02-docs-comprehensive-update-design.md

@@ -0,0 +1,187 @@
+# 全面文档整理更新设计文档
+
+**日期：** 2026-03-02
+**版本目标：** v5.5.5
+**状态：** 已批准，待实施
+
+---
+
+## 1. 背景与目标
+
+ultrapower 完成了 Batch 1~4 共 28 个痛点修复任务（v5.5.0~v5.5.5），但文档体系存在以下问题：
+
+- `docs/standards/` 中 9 个文件版本号停留在 5.0.21，与项目版本 5.5.5 严重不一致
+- `CHANGELOG.md` 缺少 v5.5.0~v5.5.4 的变更记录
+- `REFERENCE.md`、`ARCHITECTURE.md`、`FEATURES.md` 内容未反映 v5.5.x 新功能和安全修复
+- `docs/partials/` 与 `docs/shared/` 内容重复
+- `docs/reviews/`、`docs/prd/` 中存在已过期的草稿文档
+
+**目标：** 全面重组 — 版本对齐 + 内容更新 + 目录整理。
+
+---
+
+## 2. 执行方案：并行 Agent（方案 B）
+
+### 并行组 1：三个主文档完整重写
+
+| 文件 | 当前行数 | 重写目标 |
+|------|---------|---------|
+| `docs/REFERENCE.md` | 1078 行 | 基于 v5.5.5 完整重写，覆盖 49 agents、71 skills、35 tools、47 hooks、执行模式、MCP 路由 |
+| `docs/ARCHITECTURE.md` | 232 行 | 更新架构图，新增 delegation-enforcer、bridge-normalize 安全修复、Axiom 状态机章节 |
+| `docs/FEATURES.md` | 620 行 | 更新所有工具描述，新增 Axiom 集成章节、Windows 支持章节 |
+
+### 并行组 2：版本对齐 + CHANGELOG + 清理
+
+| 任务 | 范围 |
+|------|------|
+| CHANGELOG 补全 | 为 v5.5.0~v5.5.4 各添加 3~5 条精简摘要 |
+| docs/standards/ 版本升级 | 9 个文件 5.0.21/5.0.22 → 5.5.5，updated 日期 → 2026-03-02 |
+| 过期文件清理 | 删除 docs/reviews/ 中的旧版草稿、docs/prd/ 过期文档 |
+
+### 串行收尾
+
+1. 合并 `docs/shared/` → `docs/partials/`
+2. 为三个主文档添加版本头注释
+3. `npm run build && npm test` CI 验证
+4. 创建 PR：`git checkout -b docs/v5.5.5-comprehensive-update dev`
+
+---
+
+## 3. 主文档内容大纲
+
+### docs/REFERENCE.md 新结构
+
+```
+# ultrapower Reference — v5.5.5
+## Installation & Quick Start
+## Configuration
+## Execution Modes (6 modes)
+## Agents (49 个，按 Lane 分组)
+  ### Build/Analysis Lane (8)
+  ### Review Lane (6)
+  ### Domain Specialists (16)
+  ### Product Lane (4)
+  ### Axiom Lane (14)
+  ### Coordination (1)
+## Skills (71 个)
+  ### Workflow Skills
+  ### Axiom Skills
+  ### Superpowers Skills
+  ### Agent Shortcuts
+  ### Utility Skills
+## Custom Tools (35 个，8 类)
+  ### LSP Tools (12)
+  ### AST Tools (2)
+  ### Python REPL (1)
+  ### Notepad Tools (6)
+  ### State Tools (5)
+  ### Project Memory Tools (4)
+  ### Trace Tools (2)
+  ### Skills Tools (3)
+## Hooks System (47 个)
+## MCP Integration
+## Security & Safety Rules
+```
+
+### docs/ARCHITECTURE.md 新结构
+
+```
+# ultrapower Architecture — v5.5.5
+## Overview
+## Core Pipeline
+  ### Hook Bridge (bridge-normalize, SENSITIVE_HOOKS 安全修复)
+  ### Delegation Enforcer (model 自动注入)
+  ### State Manager (assertValidMode 路径防护)
+## Feature Layer
+## Axiom System
+  - 状态机: IDLE→PLANNING→CONFIRMING→EXECUTING→AUTO_FIX→BLOCKED→ARCHIVING
+  - 记忆架构
+## MCP Integration Layer
+## Security Boundaries (v5.5.5 新增)
+```
+
+### docs/FEATURES.md 新结构
+
+```
+# ultrapower Features — v5.5.5
+## Notepad System (6 tools)
+## State Management (5 tools)
+## Project Memory (4 tools)
+## LSP / AST / Python REPL
+## Delegation Enforcer (新增)
+## Axiom Integration (14 agents, 14 skills, 2 hooks)
+## Execution Modes Deep Dive
+## Hook System
+## Windows Support (v5.5.x 修复)
+## MCP Routing
+```
+
+---
+
+## 4. CHANGELOG 补全格式
+
+```markdown
+## [5.5.4] - 2026-03-02
+### Code Quality
+- Expand `generatePromptId` entropy from 4 to 8 bytes
+- Add 4MB prompt size limit to `executeGemini`
+- Unify catch blocks to return `isError: true` consistently
+- Dynamic `ALLOWED_BOUNDARIES` calculation in skills-tools
+
+## [5.5.3] - 2026-03-02
+### Documentation & Namespace
+- Replace all `superpowers:` prefix residuals with `ultrapower:`
+- Add deprecation notice for legacy namespace with migration hints
+- Sync AGENTS.md version and agent count with package.json
+- Add `$` anchor to bump-version.mjs regex; fix ax-status/ax-export paths
+- Add GitHub Actions windows-latest CI matrix
+
+## [5.5.2] - 2026-03-02
+### Feature
+- Add delegation-enforcer: auto-inject model for Task/Agent calls
+  (explore→haiku, executor→sonnet when model unspecified)
+
+## [5.5.1] - 2026-03-02
+### Fix (Windows & Features)
+- Fix `which`/`where` platform branch in auto-update
+- Fix path handling: use `path.relative()` + `path.resolve()` normalization
+- Fix `wait_for_job` max wait timeout (60s cap)
+- Fix `handleKillJob` order: kill process before writing status
+
+## [5.5.0] - 2026-03-02
+### Security
+- Add `assertValidMode()` path traversal guard at state_read/state_write entry
+- Replace `execSync` with `execFileSync` in LSP servers (shell injection fix)
+- Disable fast path for SENSITIVE_HOOKS in bridge-normalize
+- Fix `Atomics.wait()` main-thread crash: fall back to setTimeout
+- Fix Windows ESM import: use `pathToFileURL()` for daemon module loading
+- Replace config JSON.stringify injection with tmp-file + env-var pattern
+- Add 64MB buffer cap + `clearTimeout` on disconnect in LSP client
+```
+
+---
+
+## 5. 过期文件清理清单
+
+**删除：**
+- `docs/reviews/ultrapower-full-bugfix-plan/` — Batch 1~4 已完成，草稿无保留价值
+- `docs/reviews/draft-prd-ultrapower-pain-fix/` — 已被 Rough PRD + Manifest 取代
+- `docs/prd/` 中版本低于 v5.0 的草稿 PRD
+
+**保留：**
+- `docs/reviews/ultrapower-pain-points/` — 原始痛点记录，有历史价值
+- `docs/plans/` 中 2026-02 之后的计划文档
+
+---
+
+## 6. 最终交付物
+
+| 交付物 | 说明 |
+|--------|------|
+| `docs/REFERENCE.md` | 完整重写，~1200 行 |
+| `docs/ARCHITECTURE.md` | 完整重写，~300 行 |
+| `docs/FEATURES.md` | 完整重写，~700 行 |
+| `CHANGELOG.md` | 补全 v5.5.0~v5.5.4 共 20 条记录 |
+| `docs/standards/*.md` | 9 个文件版本号更新 |
+| 已删除文件 | ~3 个过期目录 |
+| PR to `dev` | `docs/v5.5.5-comprehensive-update` |