@creatoria/miniapp-mcp 0.1.2 → 0.2.0

package/docs/maintenance.md

@@ -1,682 +0,0 @@
-# Maintenance Guide
-
-This document provides guidance for maintaining the creatoria-miniapp-mcp project, including regular tasks, updates, monitoring, and troubleshooting.
-
----
-
-## 📋 Table of Contents
-
-- [Regular Maintenance Tasks](#regular-maintenance-tasks)
-- [Dependency Management](#dependency-management)
-- [Release Process](#release-process)
-- [Monitoring & Health Checks](#monitoring--health-checks)
-- [Backup & Recovery](#backup--recovery)
-- [Performance Tuning](#performance-tuning)
-- [Security Updates](#security-updates)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Regular Maintenance Tasks
-
-### Weekly Tasks
-
-#### 1. Run Smoke Tests
-
-Ensure core functionality is working:
-
-```bash
-pnpm smoke-test
-```
-
-**Expected Output**:
-- ✅ Unit Tests: 545 passing
-- ✅ Tool Count: 65 tools
-- ✅ Lint: No errors
-- ✅ Format: All files formatted
-
-**If Failed**: See [Troubleshooting](#troubleshooting) section
-
----
-
-#### 2. Check for Security Vulnerabilities
-
-Run npm audit:
-
-```bash
-pnpm audit
-```
-
-**Action Required**:
-- **High/Critical**: Fix immediately
-- **Moderate**: Schedule fix within 1 week
-- **Low**: Review and fix in next release
-
-**Fix Vulnerabilities**:
-```bash
-# Automatic fix (if available)
-pnpm audit fix
-
-# Manual fix (update specific package)
-pnpm update <package-name>
-```
-
----
-
-#### 3. Review Open Issues
-
-Check GitHub Issues for:
-- Bug reports requiring triage
-- Feature requests to evaluate
-- Questions needing answers
-
-**Triage Labels**:
-- `bug` - Confirmed bugs
-- `enhancement` - Feature requests
-- `question` - User questions
-- `good first issue` - Good for new contributors
-
----
-
-### Monthly Tasks
-
-#### 1. Dependency Updates
-
-Check for outdated dependencies:
-
-```bash
-pnpm outdated
-```
-
-**Update Strategy**:
-- **Patch updates** (0.1.0 → 0.1.1): Update immediately
-- **Minor updates** (0.1.0 → 0.2.0): Test thoroughly, update monthly
-- **Major updates** (0.1.0 → 1.0.0): Review breaking changes, plan migration
-
-**Update Process**:
-```bash
-# Update all patch versions
-pnpm update
-
-# Update specific package to latest
-pnpm update <package-name>@latest
-
-# After updating, run full test suite
-pnpm test
-pnpm smoke-test
-```
-
----
-
-#### 2. Review and Update Documentation
-
-- [ ] Check if README.md tool count matches actual tools (65)
-- [ ] Update examples if API changes occurred
-- [ ] Review troubleshooting guide for new issues
-- [ ] Check if architecture docs are up to date
-
-**Update Tool Count**:
-```bash
-pnpm update-readme
-```
-
----
-
-#### 3. Performance Monitoring
-
-Check for performance regressions:
-
-```bash
-# Run unit tests with timing
-pnpm test:unit --verbose
-
-# Check for slow tests (>1s)
-```
-
-**Performance Metrics**:
-- Unit test suite: < 10 seconds
-- Smoke test: < 20 seconds
-- Individual test: < 1 second (warn if exceeded)
-
----
-
-### Quarterly Tasks
-
-#### 1. Major Version Updates
-
-Review and plan major dependency updates:
-- TypeScript
-- Node.js (LTS versions)
-- @modelcontextprotocol/sdk
-- Jest
-- ESLint/Prettier
-
-**Process**:
-1. Create feature branch: `chore/update-deps-Q2-2025`
-2. Update one major dependency at a time
-3. Run full test suite after each update
-4. Document breaking changes in CHANGELOG.md
-5. Create PR for review
-
----
-
-#### 2. Security Audit
-
-Perform comprehensive security review:
-
-```bash
-# Run npm audit
-pnpm audit
-
-# Check for known vulnerabilities in dependencies
-npm outdated --long
-```
-
-**Review**:
-- [ ] No high/critical vulnerabilities
-- [ ] All dependencies actively maintained
-- [ ] No deprecated packages
-
----
-
-#### 3. Code Quality Review
-
-Run full quality checks:
-
-```bash
-# Type coverage
-pnpm typecheck
-
-# Lint entire codebase
-pnpm lint
-
-# Check code formatting
-pnpm format:check
-
-# Run all tests
-pnpm test
-```
-
----
-
-## Dependency Management
-
-### Updating Dependencies
-
-#### Safe Update Process
-
-```bash
-# 1. Create branch
-git checkout -b chore/update-dependencies
-
-# 2. Update patch versions
-pnpm update
-
-# 3. Run smoke test
-pnpm smoke-test
-
-# 4. Commit
-git add package.json pnpm-lock.yaml
-git commit -m "chore: update dependencies (patch)"
-
-# 5. Push and create PR
-git push origin chore/update-dependencies
-```
-
----
-
-### Critical Dependencies
-
-Monitor these closely for updates:
-
-| Dependency | Purpose | Update Frequency |
-|------------|---------|------------------|
-| `miniprogram-automator` | Core automation SDK | Check monthly |
-| `@modelcontextprotocol/sdk` | MCP protocol | Check weekly |
-| `typescript` | Type system | Minor updates only |
-| `jest` | Testing framework | Quarterly |
-
----
-
-### Known Issues
-
-#### miniprogram-automator Type Declarations
-
-**Issue**: Incomplete TypeScript type definitions
-
-**Impact**: Build warnings (not errors), does not affect runtime
-
-**Workaround**: Treated as warnings in smoke-test.sh
-
-**Long-term Fix**:
-- Contribute to upstream package
-- Or create local `.d.ts` declarations
-
----
-
-## Release Process
-
-### Automated Release via Script
-
-Use the release script for version bumping and tagging:
-
-```bash
-# Patch release (0.1.0 → 0.1.1)
-pnpm release:patch
-
-# Minor release (0.1.0 → 0.2.0)
-pnpm release:minor
-
-# Major release (0.1.0 → 1.0.0)
-pnpm release:major
-
-# Pre-release (0.1.0 → 0.1.1-0)
-pnpm release:prerelease
-```
-
-**The script will**:
-1. Run smoke tests
-2. Bump version in package.json
-3. Update README.md "Last Updated" date
-4. Create git commit
-5. Create git tag (v0.1.1)
-6. Display next steps
-
-**After Script Completes**:
-```bash
-# Push to GitHub (triggers CI/CD)
-git push origin main --tags
-```
-
-**GitHub Actions will**:
-- Create GitHub release with changelog
-- Publish to npm (stable releases only)
-
----
-
-### Manual Release Process
-
-If the script fails or you need more control:
-
-```bash
-# 1. Ensure clean working directory
-git status
-
-# 2. Run smoke test manually
-pnpm smoke-test
-
-# 3. Bump version
-pnpm version patch  # or minor/major
-
-# 4. Update docs
-# Edit README.md "Last Updated" date
-
-# 5. Commit and tag
-git add .
-git commit -m "chore: release v0.1.1"
-git tag -a v0.1.1 -m "Release v0.1.1"
-
-# 6. Push
-git push origin main --tags
-```
-
----
-
-### Release Checklist
-
-Before creating a release:
-
-- [ ] All smoke tests passing
-- [ ] README.md tool count updated (if tools changed)
-- [ ] CHANGELOG.md updated with release notes
-- [ ] No open critical bugs
-- [ ] Documentation up to date
-- [ ] Examples tested
-
----
-
-## Monitoring & Health Checks
-
-### Automated Health Checks
-
-#### GitHub Actions CI
-
-Monitors:
-- Every PR merge
-- Every push to main branch
-- Node.js 18.x and 20.x compatibility
-
-**Check Status**: https://github.com/your-org/creatoria-miniapp-mcp/actions
-
----
-
-#### Smoke Test Coverage
-
-The smoke test validates:
-
-1. **Build**: TypeScript compilation
-2. **Type Check**: tsc --noEmit
-3. **Unit Tests**: 354 tests across all tool categories
-4. **Tool Count**: Exactly 65 tools registered
-5. **Lint**: ESLint with 0 errors
-6. **Format**: Prettier compliance
-
-**Run Locally**:
-```bash
-pnpm smoke-test
-```
-
----
-
-### Manual Health Checks
-
-#### 1. Tool Registration Integrity
-
-Verify tool count hasn't regressed:
-
-```bash
-pnpm update-readme 2>&1 | grep "Total:"
-# Expected: 📊 Total: 65 tools
-```
-
----
-
-#### 2. Session Cleanup
-
-Verify session cleanup works correctly:
-
-```bash
-# Run session tests
-pnpm test tests/unit/session.test.ts
-```
-
-**Expected**: All tests pass with proper cleanup logs
-
----
-
-#### 3. Example Scripts
-
-Periodically run example scripts to ensure they work:
-
-```bash
-# Set test project
-export TEST_PROJECT_PATH="/path/to/test/miniprogram"
-
-# Run basic example
-npx tsx examples/scripts/01-basic-navigation.ts
-```
-
----
-
-## Backup & Recovery
-
-### What to Backup
-
-1. **Source Code**: Stored in Git (GitHub)
-2. **Configuration Files**:
-   - `.mcp.json` (user-specific, not in git)
-   - `package.json`
-   - `tsconfig.json`
-   - `.eslintrc.cjs`
-
-3. **Documentation**: All in git under `docs/`
-
-4. **Test Artifacts** (optional):
-   - `.mcp-artifacts/` (generated, can be recreated)
-
----
-
-### Recovery Procedures
-
-#### Recover from Git
-
-```bash
-# Clone fresh repository
-git clone https://github.com/your-org/creatoria-miniapp-mcp.git
-cd creatoria-miniapp-mcp
-
-# Install dependencies
-pnpm install
-
-# Build
-pnpm build
-
-# Verify
-pnpm smoke-test
-```
-
----
-
-#### Recover Lost Configuration
-
-If `.mcp.json` is lost:
-
-```json
-// Create new .mcp.json
-{
-  "projectPath": "/path/to/your/miniprogram",
-  "cliPath": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
-  "port": 9420
-}
-```
-
----
-
-## Performance Tuning
-
-### Identify Slow Tests
-
-```bash
-# Run tests with verbose timing
-pnpm test:unit --verbose | grep -E "PASS|FAIL|\\([0-9]+\\s*ms\\)"
-```
-
-**Action Thresholds**:
-- Test > 1 second: Investigate and optimize
-- Test suite > 10 seconds: Review test structure
-
----
-
-### Optimize Session Cleanup
-
-Default session timeout: 30 minutes
-
-**Reduce timeout for faster cleanup**:
-```javascript
-// In server config
-{
-  sessionTimeout: 10 * 60 * 1000  // 10 minutes
-}
-```
-
-**Trade-off**: Shorter timeout = more frequent cleanups, but less idle time tolerance
-
----
-
-### Tool Call Optimization
-
-Use element references to avoid repeated queries:
-
-```javascript
-// ❌ Slow: Query element each time
-await element_tap({ selector: '.btn' })
-await element_get_text({ selector: '.btn' })
-
-// ✅ Fast: Query once, use refId
-const btn = await page_query({ selector: '.btn', save: true })
-await element_tap({ refId: btn.refId })
-await element_get_text({ refId: btn.refId })
-```
-
----
-
-## Security Updates
-
-### Vulnerability Response Process
-
-1. **Detection**: `pnpm audit` or GitHub Dependabot alert
-
-2. **Assessment**:
-   - Severity: Critical/High/Moderate/Low
-   - Exploitability: Is the vulnerable code path used?
-   - Availability of fix: Is patch available?
-
-3. **Response Timeline**:
-   - **Critical**: Fix within 24 hours
-   - **High**: Fix within 1 week
-   - **Moderate**: Fix in next release cycle
-   - **Low**: Track for future update
-
-4. **Fix Application**:
-   ```bash
-   # Update vulnerable package
-   pnpm update <package-name>@<safe-version>
-
-   # Run full test suite
-   pnpm smoke-test
-
-   # Create hotfix PR
-   git checkout -b security/fix-<vulnerability-id>
-   git commit -m "security: fix <vulnerability-description>"
-   ```
-
-5. **Release**:
-   - Create patch release if critical/high
-   - Include in regular release if moderate/low
-
----
-
-### Regular Security Practices
-
-- [ ] Enable Dependabot alerts on GitHub
-- [ ] Review `pnpm audit` output weekly
-- [ ] Keep Node.js updated to LTS versions
-- [ ] Subscribe to security advisories for critical dependencies
-
----
-
-## Troubleshooting
-
-### Common Maintenance Issues
-
-#### Issue: Smoke Test Fails After Dependency Update
-
-**Symptoms**:
-```bash
-$ pnpm smoke-test
-❌ Unit Tests FAILED
-```
-
-**Diagnosis**:
-```bash
-# Run tests with verbose output
-pnpm test:unit --verbose
-
-# Check for breaking changes in updated packages
-git diff HEAD~1 package.json
-```
-
-**Resolution**:
-1. Identify which dependency caused failure
-2. Check changelog for breaking changes
-3. Update code to accommodate changes
-4. Or revert update: `pnpm install <package>@<previous-version>`
-
----
-
-#### Issue: Tool Count Mismatch
-
-**Symptoms**:
-```bash
-$ pnpm update-readme
-❌ Expected 65 tools, found 63
-```
-
-**Diagnosis**:
-```bash
-# Check which tools are missing
-pnpm update-readme 2>&1 | less
-```
-
-**Resolution**:
-1. Verify all tool files in `src/tools/` are exporting tools correctly
-2. Check `src/tools/index.ts` registration
-3. Ensure CATEGORY_METADATA matches tool arrays
-
----
-
-#### Issue: Build Fails on CI but Passes Locally
-
-**Symptoms**: GitHub Actions fail, local build succeeds
-
-**Common Causes**:
-- Node version mismatch
-- Missing environment variables
-- File system case sensitivity (macOS vs Linux)
-
-**Resolution**:
-```bash
-# Test with same Node version as CI
-nvm use 20
-
-# Clean install
-rm -rf node_modules pnpm-lock.yaml
-pnpm install
-
-# Build
-pnpm build
-```
-
----
-
-#### Issue: Release Script Fails
-
-**Symptoms**:
-```bash
-$ pnpm release:patch
-❌ Uncommitted changes detected
-```
-
-**Resolution**:
-```bash
-# Commit or stash changes first
-git status
-git add .
-git commit -m "chore: prepare for release"
-
-# Retry release
-pnpm release:patch
-```
-
----
-
-## Additional Resources
-
-### Documentation
-
-- [Troubleshooting Guide](./troubleshooting.md) - Common issues and solutions
-- [Contributing Guide](../CONTRIBUTING.md) - How to contribute
-- [Architecture](./architecture.md) - System design overview
-- [API Reference](./api/README.md) - Complete tool documentation
-
-### External Resources
-
-- [MCP Specification](https://modelcontextprotocol.io/)
-- [miniprogram-automator Docs](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
-- [Jest Documentation](https://jestjs.io/docs/getting-started)
-
----
-
-## Getting Help
-
-If you encounter issues not covered in this guide:
-
-1. **Check Existing Issues**: [GitHub Issues](https://github.com/your-org/creatoria-miniapp-mcp/issues)
-2. **Start Discussion**: [GitHub Discussions](https://github.com/your-org/creatoria-miniapp-mcp/discussions)
-3. **Contact Maintainers**: Open an issue with `question` label
-
----
-
-**Last Updated**: 2025-10-03
-**Next Review**: 2026-01-03 (Quarterly)

package/docs/playwright-mcp/350/260/203/347/240/224.md

@@ -1,53 +0,0 @@
-# Playwright MCP 调研
-
-## 仓库定位与分发形态
-- `microsoft/playwright-mcp` 提供的是一个 **薄封装**，入口文件 `index.js` 只导出 `createConnection`，实际逻辑来自 Playwright 主仓库内的 `playwright/lib/mcp/index`。
-- CLI (`cli.js`) 调用 `playwright/lib/mcp/program`，负责解析命令行并挂接 Playwright 提供的标准命令体系。
-- `src/README.md` 明确说明源码已经迁移至 Playwright monorepo；当前仓库主要承载 NPM 包装、文档与发行物。
-- NPM 包通过 `bin.mcp-server-playwright` 暴露命令行，同时支持 `exports`（默认 CommonJS、类型定义 `index.d.ts`）。
-- `package.json` 指向 Playwright alpha 版本依赖（`playwright` 与 `playwright-core` 一致版本），并依赖 `@modelcontextprotocol/sdk`、`zod-to-json-schema` 等生成工具。
-
-## Playwright 实现概览（位于 Playwright monorepo）
-### 服务器入口 (`lib/mcp/index.js`)
-- `createConnection(config, contextGetter?)` 解析配置后创建 `BrowserServerBackend`，并通过 `createServer("Playwright", version, backend)` 生成 MCP Server。
-- 支持自定义 `contextGetter`，默认使用 `contextFactory` 根据配置创建浏览器上下文。
-
-### 浏览器上下文工厂 (`lib/mcp/browser/browserContextFactory.js`)
-- 根据配置选择不同工厂：
-  - `PersistentContextFactory`：持久化 profile，默认模式。
-  - `IsolatedContextFactory`：每次会话全新 profile，适合测试。
-  - `RemoteContextFactory` 与 `CdpContextFactory`：分别连接 Playwright 远程服务或已有浏览器（CDP）。
-  - `SharedContextFactory`：多个客户端复用同一个浏览器上下文。
-- 负责注入初始化脚本、管理 userDataDir、处理追踪（trace/video）保存、CDP 端口注入等。
-
-### 服务后端 (`lib/mcp/browser/browserServerBackend.js`)
-- 在 `initialize` 中创建 `Context`（见下），并构建工具清单。
-- `callTool`：根据工具名称查找定义、校验参数（Zod schema），执行并收集响应（日志、输出、错误）。
-
-### 会话上下文 (`lib/mcp/browser/context.js`)
-- 管理 Playwright `BrowserContext` 生命周期：
-  - 懒加载创建（含网络拦截、init script、trace、session log）。
-  - 维护标签页 `Tab` 列表、当前标签切换、关闭逻辑。
-  - `InputRecorder` 记录用户操作（避免工具执行时干扰）。
-  - `outputFile` / `lookupSecret` 等辅助能力。
-- 根据配置启用网络白名单/黑名单、trace/live 截图等。
-
-### 工具体系 (`lib/mcp/browser/tools/*`)
-- 工具根据能力分组：核心自动化（导航、选择、点击、输入、截图）、标签管理、安装浏览器、坐标点击（vision 能力）、PDF、Tracing、Verify 等。
-- 文档 (`README.md`) 中的工具清单由 `update-readme.js` 读取工具 schema 自动生成，确保与实现同步。
-
-## 配置与运行模式
-- CLI 支持丰富参数：浏览器选择、CDP/Remote 连接、白/黑名单、持久化目录、init script、权限、storage state、trace/video 输出、capabilities（`vision`/`pdf`/`tracing`/`verify`）等。
-- 可作为本地 MCP (`stdio`)、HTTP 服务（`--port`）或通过浏览器扩展桥接现有浏览器会话。
-- Profile 模式：持久化（默认）/隔离/扩展（Chrome 扩展 `extension/README.md` 说明）。
-
-## 构建与发布
-- `scripts.roll` 会同步 Playwright 主仓库的 `config.d.ts` 到当前包，确保类型定义一致。
-- 使用 Playwright Test (`playwright test`) 做端到端验证，并提供 Docker 构建脚本与 CI 工作流。
-
-## 对小程序 MCP 项目的启发
-1. **工具粒度与文档生成**：Playwright 通过中心化 schema（Zod）定义工具，自动生成 README 与客户端说明；我们也可以复用这一思路，为小程序工具集提供机器可解析的描述与自动文档。
-2. **上下文管理模式**：`Context` 统一管理会话状态、标签与资源回收，适合迁移到 miniprogram-automator（例如管理 IDE 进程、页面栈、元素引用缓存）。
-3. **配置分层**：支持 CLI 参数、配置文件、环境变量三层合并（`resolveConfig`），可借鉴用于管理小程序项目路径、端口、Mock 配置等。
-4. **扩展能力开关**：通过 `capabilities` 控制额外工具（vision/pdf/tracing），小程序侧可类比启用录制、网络桩、真机远程等特性。
-5. **会话产物输出**：Playwright MCP 自动保存 trace/video/session log；我们可将截图、页面数据、断言结果统一输出，便于调试与 CI。