@miraigent/free-ai-ops-mcp 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.1.12] - 2026-06-16
+
+### Changed
+
+- Added a README success-check section so first-time npm/npx and GitHub users
+  can verify the MCP server, visible tools, and returned gate statuses before
+  opening feedback issues or connecting private workflows.
+
+## [0.1.11] - 2026-06-15
+
+### Added
+
+- Added a copy-ready faq_candidate_review example so developers can test the
+  repeated-support-question to FAQ candidate path before opening workflow
+  requests or connecting private support data.
+
 ## [0.1.10] - 2026-06-14
 
 ### Changed

package/README.md

@@ -19,8 +19,17 @@ examples/human-review-gate/.
 For a complete public-safe MCP session that covers initialize, tools/list, and
 one tool call, see examples/mcp-json-rpc-session/.
 
-If you are not a developer and only want the spreadsheet/checklist version
-first, download the free review kit:
+If the result is unclear, open a Tried It feedback issue with synthetic input
+only. A useful issue can be as small as:
+
+- the tool you ran
+- the returned status or field that was confusing
+- the review rule, risk flag, or example that would make the next run easier
+
+https://github.com/Miraigent/miraigent-free-ai-ops-mcp/issues/new?template=tried_it_feedback.md
+
+If you are not a developer and only want the spreadsheet/checklist version after
+seeing the MCP example, download the free review kit:
 
 https://miraigent.gumroad.com/l/human-review-gate-ai-drafts?utm_source=github&utm_medium=readme&utm_campaign=free-ai-ops-mcp-013
 
@@ -46,6 +55,26 @@ Claude Desktop config location:
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
+## What Success Looks Like
+
+Use this quick check before connecting private systems or opening an issue:
+
+- The MCP client starts `miraigent-free-ai-ops-mcp` without credentials.
+- `tools/list` shows four public alpha tools:
+  `human_review_gate`, `faq_candidate_review`, `ai_safe_crm_note`, and
+  `prompt_risk_review`.
+- A support-reply review returns one of `auto_ok`, `review_required`, or
+  `stop`, plus a `boundary` note that confirms the package does not send
+  messages.
+- A prompt review returns `proceed_with_checklist`,
+  `human_review_required`, or `stop_before_ai_use` before any real customer
+  data is used.
+
+If one of those checks fails, open a Tried It feedback issue with the command
+you ran, the public-safe input shape, and the returned status field. Do not
+paste private customer records, secrets, internal policy text, or paid product
+files.
+
 ## Who This Helps
 
 - Developers adding review gates to AI agents or MCP tools.
@@ -65,16 +94,25 @@ Start with the tool that matches the first unsafe handoff in your workflow:
   `ai_safe_crm_note`.
 - A prompt may touch customer data or public output: use `prompt_risk_review`.
 
+Copy-ready examples:
+
+- Human review gate: `npm run example:human-review-gate`
+- FAQ candidate review: `npm run example:faq-candidate-review`
+- Prompt risk review: `npm run example:prompt-risk-review`
+
 All examples use synthetic data. Keep private customer records, secrets,
 internal policy text, and paid product files out of public issues and screenshots.
 
 ## What To Do Next
 
 - Try one tool with synthetic data.
+- If you ran `npx @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.
 - Open a workflow request if a risk flag, status, or output field is missing.
-- Use the Gumroad kit only if you want CSV/checklist files instead of npm.
+- Use the Gumroad kit after the MCP example if you want CSV/checklist files
+  instead of npm.
 - Adapt the review-gate fields before connecting private systems or real users.
 
 Issue entry points:
@@ -207,6 +245,10 @@ Run the prompt risk review example:
 
     npm run example:prompt-risk-review
 
+Run the FAQ candidate review example:
+
+    npm run example:faq-candidate-review
+
 ## npm Package
 
 Package name: @miraigent/free-ai-ops-mcp

package/examples/faq-candidate-review/README.md

@@ -0,0 +1,33 @@
+# FAQ Candidate Review Example
+
+This example shows how to call the public faq_candidate_review MCP tool when a
+support question keeps repeating.
+
+Use it before turning repeated inquiry patterns into a public FAQ, internal FAQ,
+or human-review rule.
+
+## Run
+
+From the repository root:
+
+    npm run example:faq-candidate-review
+
+The example sends sample-request.jsonl to the MCP server and prints the
+faq_candidate_review result.
+
+## What To Look For
+
+The sample uses a low-risk pricing-plan question, so the tool should return:
+
+- recommendedStatus: public_faq_candidate
+- faqOutline: a question pattern and answer-scope hint
+- reviewSignals: frequency, response cost, and risk level
+
+## Safe Use
+
+Use synthetic examples only. Do not paste private customer records, contracts,
+payment details, internal policy text, or support inbox exports into public
+issues, examples, or screenshots.
+
+This is an operations review helper. It does not publish FAQ pages or send
+customer replies.

package/examples/faq-candidate-review/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/faq-candidate-review/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/faq-candidate-review/sample-request.jsonl

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"faq_candidate_review","arguments":{"inquiryPattern":"customers ask which pricing plan includes setup support","frequency":"high","responseCost":"medium","riskLevel":"low","currentAnswer":"Setup support is included in the team plan. Solo plans use the public setup checklist."}}}

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.10' };
+const serverInfo = { name: 'miraigent-free-ai-ops-mcp', version: '0.1.12' };
 
 const tools = [
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraigent/free-ai-ops-mcp",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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",
@@ -25,6 +25,7 @@
     "test": "node scripts/smoke-test.mjs",
     "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",
     "mcp": "node mcp/free-ai-ops-server.mjs"
   },
   "keywords": [