md-feedback 0.0.2 → 0.8.0

package/README.md

@@ -0,0 +1,72 @@
+# md-feedback
+
+> MCP server for markdown annotation review — AI agents read your annotations directly.
+
+[![npm](https://img.shields.io/npm/v/md-feedback)](https://www.npmjs.com/package/md-feedback)
+[![License: SUL-1.0](https://img.shields.io/badge/License-SUL--1.0-blue.svg)](https://github.com/yeominux/md-feedback/blob/dev/LICENSE)
+
+## What is this?
+
+md-feedback is an [MCP](https://modelcontextprotocol.io/) server that lets AI agents (Claude Code, Cursor, Copilot, etc.) read your markdown review annotations, mark memos done, evaluate quality gates, and generate session handoffs — all automatically.
+
+**This is the MCP server component.** For the VS Code extension, see [MD Feedback on VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=yeominux.md-feedback-vscode).
+
+## Quick Start
+
+Add to your MCP client config (Claude Code, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "md-feedback": {
+      "command": "npx",
+      "args": ["-y", "md-feedback"]
+    }
+  }
+}
+```
+
+That's it. No install, no setup — `npx` handles everything.
+
+## 12 MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_document_structure` | Full review state: memos, gates, cursor, sections, summary |
+| `list_annotations` | All annotations with type/status/owner/color |
+| `get_review_status` | Annotation counts and session status |
+| `update_memo_status` | Mark a memo as open/answered/done/wontfix |
+| `update_cursor` | Set plan cursor position (task ID, step, next action) |
+| `evaluate_gates` | Check if merge/release/implement conditions are met |
+| `export_review` | Export for a specific AI tool format |
+| `create_checkpoint` | Save review progress |
+| `get_checkpoints` | List all checkpoints |
+| `generate_handoff` | Generate structured handoff document |
+| `pickup_handoff` | Parse existing handoff for session resumption |
+| `create_annotation` | Create annotation programmatically |
+
+## How It Works
+
+1. You annotate a markdown plan in the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=yeominux.md-feedback-vscode)
+2. AI agent reads annotations via MCP — no export needed
+3. Agent implements fixes, marks memos done
+4. Gates auto-evaluate — agent knows when it's safe to merge
+5. Agent generates handoff — next session picks up where you left off
+
+## CLI
+
+```bash
+md-feedback --help      # Show help
+md-feedback --version   # Print version
+md-feedback             # Start MCP server (stdio)
+```
+
+## Links
+
+- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=yeominux.md-feedback-vscode)
+- [GitHub](https://github.com/yeominux/md-feedback)
+- [Documentation](https://github.com/yeominux/md-feedback#readme)
+
+## License
+
+[SUL-1.0](https://github.com/yeominux/md-feedback/blob/dev/LICENSE) — Free for personal and non-commercial use.

package/bin/md-feedback.cjs

@@ -1,3 +1,19 @@
 #!/usr/bin/env node
 
+const arg = process.argv[2]
+if (arg === '--help' || arg === '-h') {
+  console.log('md-feedback - MCP server for markdown annotation review\n')
+  console.log('Usage: md-feedback              Start MCP server (stdio transport)')
+  console.log('       md-feedback --version    Print version')
+  console.log('       md-feedback --help       Show this help\n')
+  console.log('Configure in your AI tool\'s MCP settings:')
+  console.log('  { "command": "npx", "args": ["-y", "md-feedback"] }')
+  process.exit(0)
+}
+if (arg === '--version' || arg === '-v') {
+  const pkg = require('../package.json')
+  console.log(pkg.version)
+  process.exit(0)
+}
+
 require('../dist/mcp-server.js')

package/dist/mcp-server.js

@@ -29,6 +29,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // ../../node_modules/.pnpm/ajv@8.17.1/node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -4314,11 +4315,11 @@ var require_core = __commonJS({
     Ajv2.ValidationError = validation_error_1.default;
     Ajv2.MissingRefError = ref_error_1.default;
     exports2.default = Ajv2;
-    function checkOptions(checkOpts, options, msg, log = "error") {
+    function checkOptions(checkOpts, options, msg, log2 = "error") {
       for (const key in checkOpts) {
         const opt = key;
         if (opt in options)
-          this.logger[log](`${msg}: option ${key}. ${checkOpts[opt]}`);
+          this.logger[log2](`${msg}: option ${key}. ${checkOpts[opt]}`);
       }
     }
     function getSchEnv(keyRef) {
@@ -6790,6 +6791,13 @@ var require_dist = __commonJS({
   }
 });
 
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  log: () => log
+});
+module.exports = __toCommonJS(server_exports);
+
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -22014,7 +22022,8 @@ function registerTools(server2) {
             content: [{
               type: "text",
               text: JSON.stringify({ error: "Not a valid handoff document" })
-            }]
+            }],
+            isError: true
           };
         }
         return {
@@ -22164,7 +22173,7 @@ function registerTools(server2) {
           id: `memo-${Date.now().toString(36)}`,
           type,
           status: "open",
-          owner: "human",
+          owner: "agent",
           source: "mcp",
           color,
           text,
@@ -22401,17 +22410,26 @@ function registerTools(server2) {
 }
 
 // src/server.ts
+function log(msg) {
+  process.stderr.write(`[md-feedback] ${msg}
+`);
+}
 var server = new McpServer({
   name: "md-feedback",
-  version: "0.0.1"
+  version: "0.8.0"
 });
 registerTools(server);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  log(`v${"0.8.0"} ready (stdio)`);
 }
 main().catch((err) => {
-  console.error("md-feedback MCP server error:", err);
+  log(`fatal: ${err}`);
   process.exit(1);
 });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  log
+});
 //# sourceMappingURL=mcp-server.js.map

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "md-feedback",
-  "version": "0.0.2",
+  "version": "0.8.0",
   "description": "MCP server for MD Feedback — AI agents read your markdown annotations, mark memos done, evaluate gates, and generate handoffs. No export step needed.",
   "license": "SUL-1.0",
+  "author": "Yeomin Seon",
+  "type": "commonjs",
   "bin": {
     "md-feedback": "./bin/md-feedback.cjs"
   },
   "files": [
     "dist/mcp-server.js",
-    "bin/md-feedback.cjs"
+    "bin/md-feedback.cjs",
+    "README.md"
   ],
+  "scripts": {
+    "build": "node esbuild.mjs"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0"
@@ -46,8 +52,5 @@
     "cursor-ai",
     "gates",
     "plan-cursor"
-  ],
-  "scripts": {
-    "build": "node esbuild.mjs"
-  }
-}
+  ]
+}

package/LICENSE

@@ -1,75 +0,0 @@
-Sustainable Use License
-
-Version 1.0
-
-Copyright (c) 2026 Yeomin Seon
-
-Acceptance
-
-By using the software, you agree to all of the terms and conditions below.
-
-Copyright License
-
-The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
-to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
-to the limitations below.
-
-Limitations
-
-You may use or modify the software only for your own internal business purposes or for non-commercial or
-personal use. You may distribute the software or provide it to others only if you do so free of charge for
-non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
-the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
-
-Patents
-
-The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
-license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
-subject to the limitations and conditions in this license. This license does not cover any patent claims that
-you cause to be infringed by modifications or additions to the software. If you or your company make any
-written claim that the software infringes or contributes to infringement of any patent, your patent license
-for the software granted under these terms ends immediately. If your company makes such a claim, your patent
-license ends immediately for work on behalf of your company.
-
-Notices
-
-You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
-terms. If you modify the software, you must include in any modified copies of the software a prominent notice
-stating that you have modified the software.
-
-No Other Rights
-
-These terms do not imply any licenses other than those expressly granted in these terms.
-
-Termination
-
-If you use the software in violation of these terms, such use is not licensed, and your license will
-automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
-violation of this license no later than 30 days after you receive that notice, your license will be reinstated
-retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
-terms will cause your license to terminate automatically and permanently.
-
-No Liability
-
-As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
-not be liable to you for any damages arising out of these terms or the use or nature of the software, under
-any kind of legal claim.
-
-Definitions
-
-The "licensor" is the entity offering these terms, Yeomin Seon.
-
-The "software" is the software the licensor makes available under these terms, including any portion of it.
-
-"You" refers to the individual or entity agreeing to these terms.
-
-"Your company" is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
-all organizations that have control over, are under the control of, or are under common control with that
-organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
-management and policies by vote, contract, or otherwise. Control can be direct or indirect.
-
-"Your license" is the license granted to you for the software under these terms.
-
-"Use" means anything you do with the software requiring your license.
-
-"Trademark" means trademarks, service marks, and similar rights.