@miraigent/free-ai-ops-mcp 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.1.20] - 2026-06-20
+
+### Added
+
+- Added a copy-ready ai_safe_crm_note example so developers can test separating
+  customer facts, AI suggestions, human decisions, and next actions before
+  connecting private CRM notes.
+
+## [0.1.19] - 2026-06-19
+
+### Fixed
+
+- Updated README, help output, and MCP client config examples to the verified
+  npm alias command `npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp`,
+  which resolves the scoped package binary consistently in public tests.
+
 ## [0.1.18] - 2026-06-19
 
 ### Fixed

package/README.md

@@ -11,7 +11,7 @@ reaches customers or shared systems.
 
 Run the public MCP server:
 
-    npm exec --yes --package=@miraigent/free-ai-ops-mcp -- free-ai-ops-mcp
+    npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp
 
 Then send a JSON-RPC tool call such as the copy-ready example in
 examples/human-review-gate/.
@@ -24,7 +24,7 @@ one tool call, see examples/mcp-json-rpc-session/.
 Use this when you want to confirm the npm package works before editing a desktop
 MCP client config:
 
-    npm exec --yes --package=@miraigent/free-ai-ops-mcp -- free-ai-ops-mcp < examples/mcp-json-rpc-session/sample-session.jsonl
+    npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp < examples/mcp-json-rpc-session/sample-session.jsonl
 
 The response should include:
 
@@ -39,7 +39,7 @@ the command, synthetic input shape, and returned status only.
 
 If you are checking the package from npm search, run the public help first:
 
-    npm exec --yes --package=@miraigent/free-ai-ops-mcp -- free-ai-ops-mcp --help
+    npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp --help
 
 The help output lists the available MCP tools, the one-command smoke test, and
 the public-safe boundary before you send any JSON-RPC input.
@@ -66,7 +66,7 @@ Add to your `claude_desktop_config.json` or Cursor MCP settings:
       "mcpServers": {
         "miraigent-free-ai-ops-mcp": {
           "command": "npx",
-          "args": ["-y", "@miraigent/free-ai-ops-mcp"]
+          "args": ["-y", "free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp"]
         }
       }
     }
@@ -107,7 +107,7 @@ public-safe result shape that shows where the review gate helped or felt unclear
 
 Good public-safe issue body:
 
-    Command: npx @miraigent/free-ai-ops-mcp
+    Command: npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp
     Tool: human_review_gate
     Input shape:
       draftType: customer support reply
@@ -144,6 +144,7 @@ Copy-ready examples:
 
 - Human review gate: `npm run example:human-review-gate`
 - FAQ candidate review: `npm run example:faq-candidate-review`
+- AI-safe CRM note: `npm run example:ai-safe-crm-note`
 - Prompt risk review: `npm run example:prompt-risk-review`
 
 All examples use synthetic data. Keep private customer records, secrets,
@@ -152,7 +153,7 @@ internal policy text, and paid product files out of public issues and screenshot
 ## What To Do Next
 
 - Try one tool with synthetic data.
-- If you ran `npm exec --yes --package=@miraigent/free-ai-ops-mcp -- free-ai-ops-mcp`, paste the public-safe result
+- If you ran `npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp`, paste the public-safe result
   shape into the Tried It feedback issue.
 - Share what happened in the Tried It feedback issue if setup, JSON-RPC input,
   or the returned gate decision was unclear.
@@ -272,7 +273,7 @@ developer-focused distribution route.
 
 Run from npm:
 
-    npx @miraigent/free-ai-ops-mcp
+    npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp
 
 Run checks:
 
@@ -295,13 +296,17 @@ Run the FAQ candidate review example:
 
     npm run example:faq-candidate-review
 
+Run the AI-safe CRM note example:
+
+    npm run example:ai-safe-crm-note
+
 ## npm Package
 
 Package name: @miraigent/free-ai-ops-mcp
 
 Command:
 
-    npx @miraigent/free-ai-ops-mcp
+    npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp
 
 ## Public Boundary
 

package/examples/ai-safe-crm-note/README.md

@@ -0,0 +1,33 @@
+# AI-Safe CRM Note Example
+
+This example shows how to call the public ai_safe_crm_note MCP tool before a
+support, sales, or onboarding note is copied into a CRM.
+
+Use it when a note mixes customer facts, AI suggestions, human decisions, and
+next actions in one paragraph.
+
+## Run
+
+From the repository root:
+
+    npm run example:ai-safe-crm-note
+
+The example sends sample-request.jsonl to the MCP server and prints the
+ai_safe_crm_note result.
+
+## What To Look For
+
+The sample uses a public-safe setup-timing note, so the tool should return:
+
+- crmNote.customerFacts: the factual summary only
+- crmNote.aiSuggestion: a separate AI suggestion placeholder
+- crmNote.humanDecision: a separate human decision placeholder
+- crmNote.nextAction: the next support or sales action
+
+## Safe Use
+
+Use synthetic examples only. Do not paste private customer records, names,
+emails, phone numbers, account IDs, contracts, payment details, internal policy
+text, or CRM exports into public issues, examples, or screenshots.
+
+This is an operations note helper. It does not write to a CRM or call an AI API.

package/examples/ai-safe-crm-note/run-example.mjs

@@ -0,0 +1,28 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+const child = spawn(process.execPath, ['mcp/free-ai-ops-server.mjs'], {
+  stdio: ['pipe', 'pipe', 'inherit']
+});
+
+const request = fs.readFileSync('examples/ai-safe-crm-note/sample-request.jsonl', 'utf8');
+let stdout = '';
+
+child.stdout.on('data', (chunk) => {
+  stdout += chunk;
+});
+
+child.stdin.write(request.trim() + '\n');
+child.stdin.end();
+
+await new Promise((resolve, reject) => {
+  child.on('error', reject);
+  child.on('close', (code) => {
+    if (code !== 0) reject(new Error('server exited with ' + code));
+    else resolve();
+  });
+});
+
+const response = JSON.parse(stdout.trim());
+const payload = JSON.parse(response.result.content[0].text);
+console.log(JSON.stringify(payload, null, 2));

package/examples/ai-safe-crm-note/sample-request.jsonl

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ai_safe_crm_note","arguments":{"rawNoteSummary":"Customer asked whether setup can start this week and wants the checklist before the kickoff call.","channel":"contact form","containsPersonalData":false,"nextAction":"send setup checklist and confirm kickoff date","owner":"sales operations"}}}

package/mcp/free-ai-ops-server.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const serverInfo = { name: 'miraigent-free-ai-ops-mcp', version: '0.1.18' };
+const serverInfo = { name: 'miraigent-free-ai-ops-mcp', version: '0.1.20' };
 
 const tools = [
   {
@@ -69,10 +69,10 @@ function printHelp() {
   process.stdout.write(`Miraigent Free AI Ops MCP ${serverInfo.version}
 
 Run the public MCP server:
-  npm exec --yes --package=@miraigent/free-ai-ops-mcp -- free-ai-ops-mcp
+  npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp
 
 Run a copy-ready public smoke test:
-  npm exec --yes --package=@miraigent/free-ai-ops-mcp -- free-ai-ops-mcp < examples/mcp-json-rpc-session/sample-session.jsonl
+  npx -y free-ai-ops-mcp@npm:@miraigent/free-ai-ops-mcp < examples/mcp-json-rpc-session/sample-session.jsonl
 
 Available tools:
   human_review_gate      Stop/review/approve AI drafts before sending

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraigent/free-ai-ops-mcp",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Free MCP server for developers adding human review gates, prompt risk checks, FAQ review, and CRM note safety to AI tools.",
   "homepage": "https://github.com/Miraigent/miraigent-free-ai-ops-mcp",
   "type": "module",
@@ -26,6 +26,7 @@
     "example:human-review-gate": "node examples/human-review-gate/run-example.mjs",
     "example:prompt-risk-review": "node examples/prompt-risk-review/run-example.mjs",
     "example:faq-candidate-review": "node examples/faq-candidate-review/run-example.mjs",
+    "example:ai-safe-crm-note": "node examples/ai-safe-crm-note/run-example.mjs",
     "mcp": "node mcp/free-ai-ops-server.mjs"
   },
   "keywords": [

package/scripts/smoke-test.mjs

@@ -21,7 +21,7 @@ await new Promise((resolve, reject) => {
   });
 });
 
-assert.match(helpStdout, /npm exec --yes --package=@miraigent\/free-ai-ops-mcp/);
+assert.match(helpStdout, /npx -y free-ai-ops-mcp@npm:@miraigent\/free-ai-ops-mcp/);
 assert.match(helpStdout, /human_review_gate/);
 assert.match(helpStdout, /Do not paste secrets/);