@granoflow/mcp-server 0.1.2 → 0.1.3

package/README.md

@@ -42,6 +42,12 @@ file; keep `GRANOFLOW_API_TOKEN` in the MCP client environment.
 npm install -g @granoflow/mcp-server
 ```
 
+For a user-facing setup walkthrough, see
+[Granoflow MCP User Install And Demo Guide](docs/user-install-demo.md).
+
+For maintainers, see
+[Granoflow MCP Release Checklist](docs/release-checklist.md).
+
 For local development:
 
 ```bash

package/dist/metadata.d.ts

@@ -1,2 +1,2 @@
 export declare const SERVER_NAME = "granoflow-mcp-server";
-export declare const SERVER_VERSION = "0.1.2";
+export declare const SERVER_VERSION = "0.1.3";

package/dist/metadata.js

@@ -1,3 +1,3 @@
 export const SERVER_NAME = "granoflow-mcp-server";
-export const SERVER_VERSION = "0.1.2";
+export const SERVER_VERSION = "0.1.3";
 //# sourceMappingURL=metadata.js.map

package/docs/release-checklist.md

@@ -0,0 +1,144 @@
+# Granoflow MCP Release Checklist
+
+Use this checklist before publishing a new `@granoflow/mcp-server` version.
+
+## 1. Source State
+
+- Confirm the worktree is clean or only contains intended release changes:
+
+  ```bash
+  git status --short --branch
+  ```
+
+- Confirm the package version, runtime metadata, and tests agree:
+
+  ```bash
+  node -p "require('./package.json').version"
+  npm run check
+  node dist/index.js --version
+  ```
+
+## 2. Static Gates
+
+Run the project gate:
+
+```bash
+npm run check
+```
+
+The gate must pass:
+
+- Prettier
+- ESLint
+- TypeScript build
+- Vitest
+
+## 3. Package Contents
+
+Inspect the packed files:
+
+```bash
+npm pack --json
+```
+
+Verify:
+
+- `dist/index.js` is present.
+- `dist/index.js` mode is executable, for example `493`.
+- `README.md` is present.
+- `docs/` files are present when documentation changed.
+- no obsolete `dist/cli.*` files are present.
+- no local config, token, recovery code, or temporary file is present.
+
+Remove the generated `.tgz` after inspection unless you intentionally need it:
+
+```bash
+rm -f granoflow-mcp-server-*.tgz
+```
+
+## 4. Local MCP Smoke
+
+Start the package through stdio and list tools. The smoke should prove:
+
+- expected tool count is returned.
+- `granoflow_health` returns `code: "ok"` when Granoflow is running.
+- resource tools such as project, milestone, and structured task tools exist.
+- write tools can return `code: "dry_run"` without creating real data.
+
+## 5. App Runtime Evidence
+
+Verify the running Granoflow app:
+
+```bash
+curl -s http://127.0.0.1:56789/v1/health
+```
+
+For macOS production app verification, `granoflow_setup_status` should show a
+process path like:
+
+```text
+/Applications/granoflow.app/Contents/MacOS/granoflow
+```
+
+## 6. Client Config Examples
+
+Confirm README and docs show the same command shape:
+
+```text
+command = "npx"
+args = ["-y", "@granoflow/mcp-server"]
+```
+
+Cursor and Codex examples should set:
+
+```text
+GRANOFLOW_API_BASE_URL=http://127.0.0.1:56789
+```
+
+Do not add API tokens to checked-in examples.
+
+## 7. Secret And Drift Checks
+
+Search for obsolete command-wrapper references and secret-like values:
+
+```bash
+rg -n "granoflow-cli|GRANOFLOW_CLI|cliPath|granoflow_cli" README.md docs src tests package.json AGENTS.md
+rg -n "recovery code|_authToken|secret-token|npm password" README.md docs src tests package.json AGENTS.md
+```
+
+Expected result:
+
+- no obsolete command-wrapper dependency.
+- no real token, OTP, password, or recovery code.
+- test fixtures may use fake values only when they assert redaction.
+
+## 8. Publish
+
+Publish only after all previous checks pass:
+
+```bash
+npm publish --access public
+```
+
+If npm requires two-factor authentication, provide an OTP through the command
+line without printing it in logs. Do not paste OTPs or recovery codes into issue
+reports, docs, screenshots, or chat transcripts.
+
+## 9. Post-Publish Verification
+
+Verify the published package:
+
+```bash
+npm access get status @granoflow/mcp-server
+npm dist-tag ls @granoflow/mcp-server
+npx -y @granoflow/mcp-server@<version> --version
+npx -y @granoflow/mcp-server --version
+```
+
+Run one MCP stdio smoke against the published version:
+
+- list tools
+- call `granoflow_health`
+- call one dry-run write tool
+
+Only then write release notes or mark the release task done.

package/docs/user-install-demo.md

@@ -0,0 +1,140 @@
+# Granoflow MCP User Install And Demo Guide
+
+This guide helps you connect Codex or Cursor to the Granoflow desktop app
+through the Granoflow Local HTTP API.
+
+## 1. Start Granoflow
+
+Open the installed Granoflow desktop app. On macOS the production app is usually:
+
+```text
+/Applications/granoflow.app
+```
+
+In Granoflow, open the local interface service page and turn on the Local HTTP
+API. The default local address is:
+
+```text
+http://127.0.0.1:56789
+```
+
+Verify the app is reachable:
+
+```bash
+curl -s http://127.0.0.1:56789/v1/health
+```
+
+A healthy response includes `status`, `apiEnabled`, `running`, and `version`.
+
+## 2. Check The MCP Package
+
+Verify the npm package can run:
+
+```bash
+npx -y @granoflow/mcp-server --version
+```
+
+The command should print the package version.
+
+## 3. Configure Codex
+
+Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.granoflow]
+type = "stdio"
+command = "npx"
+args = ["-y", "@granoflow/mcp-server"]
+
+[mcp_servers.granoflow.env]
+GRANOFLOW_API_BASE_URL = "http://127.0.0.1:56789"
+```
+
+Restart Codex or reload MCP servers after changing the file.
+
+## 4. Configure Cursor
+
+Add this to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "granoflow": {
+      "command": "npx",
+      "args": ["-y", "@granoflow/mcp-server"],
+      "env": {
+        "GRANOFLOW_API_BASE_URL": "http://127.0.0.1:56789"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor or reload MCP servers after changing the file.
+
+## 5. First Demo
+
+Ask your MCP client to call:
+
+- `granoflow_health`
+- `granoflow_version`
+- `granoflow_task_list`
+
+Expected result:
+
+- health returns `code: "ok"`
+- version returns Granoflow app version metadata
+- task list returns your current Granoflow tasks
+
+## 6. Dry-Run Write Demo
+
+Use a dry-run before any write. For example, ask the MCP client to call
+`granoflow_task_create_structured` with:
+
+```json
+{
+  "title": "MCP dry-run test",
+  "description": "This request should preview only.",
+  "dryRun": true
+}
+```
+
+Expected result:
+
+```json
+{
+  "code": "dry_run"
+}
+```
+
+The dry-run preview should not create a real task.
+
+## Troubleshooting
+
+### The health check cannot connect
+
+Check that Granoflow is open and that the Local HTTP API is enabled in the app.
+If you changed the port in Granoflow, update `GRANOFLOW_API_BASE_URL` in your MCP
+client config.
+
+### The MCP client does not show Granoflow tools
+
+Restart Codex or Cursor after editing the MCP config. Also verify:
+
+```bash
+npx -y @granoflow/mcp-server --version
+```
+
+### The MCP client connects to the wrong app
+
+Call `granoflow_setup_status`. On macOS, the process evidence should point to
+the production app when that is what you intended:
+
+```text
+/Applications/granoflow.app/Contents/MacOS/granoflow
+```
+
+### You enabled an API token
+
+Keep the token in the MCP client environment. Do not paste real tokens into
+docs, screenshots, issue reports, or chat transcripts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granoflow/mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server for Granoflow: exposes the Local HTTP API as tools for AI agents, IDEs, and automation.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],