calc-mcp-server 0.1.0

package/.claude/commands/opsx/verify.md

@@ -0,0 +1,164 @@
+---
+name: "OPSX: Verify"
+description: Verify implementation matches change artifacts before archiving
+category: Workflow
+tags: [workflow, verify, experimental]
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm whoami)",
+      "Bash(npm config get registry)"
+    ]
+  }
+}

package/.claude/skills/npm-publish/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: npm-publish
+description: 发布 @neosamon/calc-mcp-server 到 npm。当用户想要发布新版本或更新包时使用。
+license: MIT
+compatibility: Requires npm, Node.js 18+, and valid npm credentials.
+metadata:
+  author: neosamon
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+发布 `@neosamon/calc-mcp-server` 到 npm registry。
+
+**输入**：用户可以指定版本更新类型（patch/minor/major）或具体版本号。默认为 patch。
+
+**步骤**
+
+1. **验证前置条件**
+
+   在发布前验证以下条件：
+
+   ```bash
+   # 检查 npm 登录状态
+   npm whoami
+
+   # 检查当前 registry
+   npm config get registry
+
+   # 如果不是官方 registry，提示切换
+   # npm config set registry https://registry.npmjs.org/
+   ```
+
+   **如果未登录 npm**：
+   - 提示用户需要 Granular Access Token
+   - 参考用户使用 AskUserQuestion：
+     > "你还没有登录 npm。需要先配置 Granular Access Token。是否需要配置说明？"
+
+2. **检查当前版本号**
+
+   ```bash
+   npm view @neosamon/calc-mcp-server version
+   ```
+
+3. **确定版本更新类型**
+
+   使用 **AskUserQuestion Tool** 询问版本更新类型：
+
+   > "选择版本更新类型：
+   > - **patch** (x.x.X): 修复 bug，向下兼容的问题修正
+   > - **minor** (x.X.x): 新增功能，向下兼容的功能性新增
+   > - **major** (X.x.x): 破坏性变更，不向下兼容的 API 修改
+   > - **custom**: 手动指定版本号"
+
+4. **执行版本更新**
+
+   根据用户选择执行对应的命令：
+
+   ```bash
+   # patch: 修复 bug
+   npm version patch
+
+   # minor: 新增功能
+   npm version minor
+
+   # major: 破坏性变更
+   npm version major
+
+   # custom: 手动指定
+   npm version <version>
+   ```
+
+5. **清理并编译**
+
+   ```bash
+   # 清理旧的构建产物
+   rm -rf build node_modules
+
+   # 安装依赖
+   npm install
+
+   # 编译 TypeScript
+   npm run build
+   ```
+
+6. **验证编译结果**
+
+   ```bash
+   # 验证 shebang（可执行文件头）
+   head -1 build/index.js
+   # 应该输出: #!/usr/bin/env node
+   ```
+
+   **如果 shebang 不正确**：
+   - 报告错误并要求修复 `src/index.ts` 第一行
+
+7. **发布到 npm**
+
+   ```bash
+   npm publish --access public
+   ```
+
+8. **验证发布结果**
+
+   ```bash
+   # 查看包信息
+   npm view @neosamon/calc-mcp-server
+   ```
+
+9. **询问是否恢复淘宝镜像（可选）**
+
+   使用 **AskUserQuestion Tool**：
+   > "发布成功！是否需要恢复淘宝镜像以加速其他包的安装？"
+
+   如果确认，执行：
+   ```bash
+   npm config set registry https://registry.npmmirror.com/
+   ```
+
+**输出**
+
+完成发布后，显示：
+- 新版本号
+- npm 包信息
+- 发布时间
+- 安装测试命令
+- 提示："已成功发布到 npm！可以使用 `npx @neosamon/calc-mcp-server` 安装使用。"
+
+**快速发布模式**
+
+如果用户输入 `/npm-publish --fast` 或类似快捷模式：
+- 跳过版本更新确认，默认使用 patch
+- 执行清理、编译、发布一条龙流程
+- 命令：`rm -rf build node_modules && npm install && npm run build && npm version patch && npm publish --access public`
+
+**护栏**
+
+- **必须**验证 npm 登录状态，未登录时停止并提示
+- **必须**确认使用官方 registry，淘宝镜像会导致发布失败
+- **必须**验证编译成功后再发布
+- **不要**在发布失败后自动重试（可能覆盖已有版本）
+- **不要**跳过版本更新步骤（避免版本冲突）
+
+**发布前检查清单**
+
+- [ ] npm 已登录 (`npm whoami`)
+- [ ] 使用官方 registry (`npm config get registry`)
+- [ ] 代码已编译 (`npm run build`)
+- [ ] shebang 正确 (`head -1 build/index.js`)
+- [ ] 版本号已更新
+
+**常见错误处理**
+
+| 错误 | 原因 | 解决方案 |
+|------|------|---------|
+| 403 Forbidden | 2FA required | 使用 Granular Access Token 并启用 "2FA bypass" |
+| 401 Unauthorized | Token 过期/无效 | 重新创建并配置 Token |
+| E403 | 权限不足 | 确认属于 @neosamon 组织且有 Publish 权限 |
+| command not found | shebang 缺失 | 检查 `src/index.ts` 第一行是否为 `#!/usr/bin/env node` |
+
+**相关文档**
+
+- [PUBLISH.md](../PUBLISH.md) - 详细发布文档
+- [DEVELOPMENT.md](../DEVELOPMENT.md) - 开发指南
+- [npm 发布文档](https://docs.npm.com/cli/v9/commands/npm-publish)

package/.claude/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: 实施 OpenSpec 变更中的任务。当用户想要开始实施、继续实施或处理任务时使用。
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+实施 OpenSpec 变更中的任务。
+
+**输入**：可选择指定变更名称。如果省略，检查是否可以从对话上下文中推断。如果模糊或不明确，必须提示可用的变更。
+
+**步骤**
+
+1. **选择变更**
+
+   如果提供了名称，使用它。否则：
+   - 如果用户提到变更，从对话上下文中推断
+   - 如果只有一个活跃变更，自动选择
+   - 如果模糊，运行 `openspec list --json` 获取可用变更，并使用 **AskUserQuestion 工具** 让用户选择
+
+   始终宣布："正在使用变更：<name>" 以及如何覆盖（例如，`/opsx:apply <other>`）。
+
+2. **检查状态以了解 Schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   解析 JSON 以了解：
+   - `schemaName`：正在使用的工作流（例如，"spec-driven"）
+   - 哪个产物包含任务（通常是 "tasks"，对于其他 Schema 检查状态）
+
+3. **获取实施指令**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   这返回：
+   - 上下文文件路径（因 Schema 而异 - 可能是 proposal/specs/design/tasks 或 spec/tests/implementation/docs）
+   - 进度（总数，完成，剩余）
+   - 带状态的任务列表
+   - 基于当前状态的动态指令
+
+   **处理状态：**
+   - 如果 `state: "blocked"`（缺少产物）：显示消息，建议使用 openspec-continue-change
+   - 如果 `state: "all_done"`：祝贺，建议归档
+   - 否则：继续实施
+
+4. **阅读上下文文件**
+
+   阅读实施指令输出中 `contextFiles` 列出的文件。
+   文件取决于正在使用的 Schema：
+   - **spec-driven**：proposal, specs, design, tasks
+   - 其他 Schema：遵循 CLI 输出中的 contextFiles
+
+5. **显示当前进度**
+
+   显示：
+   - 正在使用的 Schema
+   - 进度："N/M 任务完成"
+   - 剩余任务概览
+   - 来自 CLI 的动态指令
+
+6. **实施任务（循环直到完成或阻塞）**
+
+   对于每个待处理任务：
+   - 显示正在处理哪个任务
+   - 进行所需的代码更改
+   - 保持更改最小且专注
+   - 在任务文件中标记任务完成：`- [ ]` → `- [x]`
+   - 继续下一个任务
+
+   **暂停如果：**
+   - 任务不清楚 → 寻求澄清
+   - 实施揭示了设计问题 → 建议更新产物
+   - 遇到错误或阻碍 → 报告并等待指导
+   - 用户打断
+
+7. **完成或暂停时，显示状态**
+
+   显示：
+   - 本次会话完成的任务
+   - 总体进度："N/M 任务完成"
+   - 如果全部完成：建议归档
+   - 如果暂停：解释原因并等待指导
+
+**实施期间的输出**
+
+```
+## 正在实施：<change-name> (schema: <schema-name>)
+
+正在处理任务 3/7：<task description>
+[...实施中...]
+✓ 任务完成
+
+正在处理任务 4/7：<task description>
+[...实施中...]
+✓ 任务完成
+```
+
+**完成时的输出**
+
+```
+## 实施完成
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**进度：** 7/7 任务完成 ✓
+
+### 本次会话完成
+- [x] Task 1
+- [x] Task 2
+...
+
+所有任务完成！准备归档此变更。
+```
+
+**暂停时的输出（遇到问题）**
+
+```
+## 实施暂停
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**进度：** 4/7 任务完成
+
+### 遇到的问题
+<description of the issue>
+
+**选项：**
+1. <option 1>
+2. <option 2>
+3. 其他方法
+
+你想怎么做？
+```
+
+**护栏**
+- 继续处理任务直到完成或阻塞
+- 开始前始终阅读上下文文件（来自实施指令输出）
+- 如果任务模糊，在实施前暂停并询问
+- 如果实施揭示了问题，暂停并建议更新产物
+- 保持代码更改最小并限定在每个任务范围内
+- 完成每个任务后立即更新任务复选框
+- 遇到错误、阻碍或不明确的需求时暂停 - 不要猜测
+- 使用 CLI 输出中的 contextFiles，不要假设特定的文件名
+
+**流畅的工作流集成**
+
+此技能支持 "对变更的操作" 模型：
+
+- **可以随时调用**：在所有产物完成之前（如果任务存在），部分实施后，与其他操作交错
+- **允许产物更新**：如果实施揭示了设计问题，建议更新产物 - 不是阶段锁定的，流畅工作

package/.claude/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: openspec-archive-change
+description: 在实验性工作流中归档已完成的变更。当用户想要在实施完成后最终确定并归档变更时使用。
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+在实验性工作流中归档已完成的变更。
+
+**输入**：可选择指定变更名称。如果省略，检查是否可以从对话上下文中推断。如果模糊或不明确，必须提示可用的变更。
+
+**步骤**
+
+1. **如果没有提供变更名称，提示选择**
+
+   运行 `openspec list --json` 获取可用变更。使用 **AskUserQuestion 工具** 让用户选择。
+
+   仅显示活跃变更（未归档）。
+   如果可用，包括每个变更使用的 Schema。
+
+   **重要**：不要猜测或自动选择变更。始终让用户选择。
+
+2. **检查产物完成状态**
+
+   运行 `openspec status --change "<name>" --json` 检查产物完成情况。
+
+   解析 JSON 以了解：
+   - `schemaName`：正在使用的工作流
+   - `artifacts`：产物列表及其状态（`done` 或其他）
+
+   **如果有产物未 `done`：**
+   - 显示列出未完成产物的警告
+   - 使用 **AskUserQuestion 工具** 确认用户是否要继续
+   - 如果用户确认则继续
+
+3. **检查任务完成状态**
+
+   阅读任务文件（通常是 `tasks.md`）以检查未完成的任务。
+
+   统计标记为 `- [ ]`（未完成）与 `- [x]`（完成）的任务。
+
+   **如果发现未完成的任务：**
+   - 显示列出未完成任务计数的警告
+   - 使用 **AskUserQuestion 工具** 确认用户是否要继续
+   - 如果用户确认则继续
+
+   **如果不存在任务文件：** 继续而不显示任务相关警告。
+
+4. **评估增量规范同步状态**
+
+   检查 `openspec/changes/<name>/specs/` 中的增量规范。如果不存在，继续而不显示同步提示。
+
+   **如果存在增量规范：**
+   - 将每个增量规范与 `openspec/specs/<capability>/spec.md` 中的对应主规范进行比较
+   - 确定将应用哪些更改（添加、修改、删除、重命名）
+   - 在提示之前显示合并总结
+
+   **提示选项：**
+   - 如果需要更改："立即同步（推荐）"，"归档而不同步"
+   - 如果已同步："立即归档"，"仍然同步"，"取消"
+
+   如果用户选择同步，使用 Task 工具（subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"）。无论选择如何，都继续归档。
+
+5. **执行归档**
+
+   如果归档目录不存在，创建它：
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   使用当前日期生成目标名称：`YYYY-MM-DD-<change-name>`
+
+   **检查目标是否已存在：**
+   - 如果是：报错失败，建议重命名现有归档或使用不同日期
+   - 如果否：将变更目录移动到归档
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **显示总结**
+
+   显示归档完成总结，包括：
+   - 变更名称
+   - 使用的 Schema
+   - 归档位置
+   - 规范同步状态（已同步 / 跳过同步 / 无增量规范）
+   - 关于任何警告的说明（未完成的产物/任务）
+
+**成功时的输出**
+
+```
+## 归档完成
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**归档至：** openspec/changes/archive/YYYY-MM-DD-<name>/
+**规范：** ✓ 已同步到主规范
+
+所有产物已完成。所有任务已完成。
+```
+
+**成功时的输出（无增量规范）**
+
+```
+## 归档完成
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**归档至：** openspec/changes/archive/YYYY-MM-DD-<name>/
+**规范：** 无增量规范
+
+所有产物已完成。所有任务已完成。
+```
+
+**带警告的成功输出**
+
+```
+## 归档完成（带警告）
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**归档至：** openspec/changes/archive/YYYY-MM-DD-<name>/
+**规范：** 同步已跳过（用户选择跳过）
+
+**警告：**
+- 归档时有 2 个未完成的产物
+- 归档时有 3 个未完成的任务
+- 增量规范同步已跳过（用户选择跳过）
+
+如果这不是故意的，请检查归档。
+```
+
+**错误时的输出（归档已存在）**
+
+```
+## 归档失败
+
+**变更：** <change-name>
+**目标：** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+目标归档目录已存在。
+
+**选项：**
+1. 重命名现有的归档
+2. 如果是重复的，删除现有的归档
+3. 等到不同的日期再归档
+```
+
+**护栏**
+- 如果未提供，始终提示选择变更
+- 使用产物图 (openspec status --json) 进行完成检查
+- 不要因警告阻止归档 - 只需通知并确认
+- 移动到归档时保留 .openspec.yaml（它随目录移动）
+- 显示发生的清晰总结
+- 如果请求同步，使用 Skill 工具调用 `openspec-sync-specs`（Agent 驱动）
+- 如果存在增量规范，始终运行同步评估并在提示前显示合并总结