@holdyourvoice/hyv 3.0.0 → 3.0.2

package/Readme.md

@@ -1,5 +1,8 @@
 # Hold Your Voice
 
+[![npm downloads](https://img.shields.io/npm/dt/%40holdyourvoice%2Fhyv?label=npm%20downloads&color=2f81f7)](https://www.npmjs.com/package/@holdyourvoice/hyv)
+
+
 Hold Your Voice is an MIT-licensed, local-first writing gate for people who want AI help without losing the parts of their writing that make it theirs.
 
 It checks a draft through two separate programs:
@@ -9,7 +12,7 @@ It checks a draft through two separate programs:
 
 Those programs keep separate findings, scores, and pass states. A strong result from one never cancels a failure in the other. The tool creates a tiered editing brief, then checks the candidate again before you accept it.
 
-Everything runs from local files: accounts, API calls, MCP servers, telemetry, payment collection, and runtime network requests stay out of the core path.
+Everything in the CLI runs from local files: accounts, API calls, telemetry, payment collection, and runtime network requests stay out of the core path. The optional Claude extension adds a local stdio MCP adapter around that same engine; it is not a hosted service.
 
 > **Status:** the public CLI is published as [`@holdyourvoice/hyv`](https://www.npmjs.com/package/@holdyourvoice/hyv). It runs locally and makes no runtime network requests.
 
@@ -50,6 +53,21 @@ hyv patterns
 
 To contribute, clone this repository, run `npm install`, then run `npm test` and `npm run check:release`.
 
+### Use it in Claude Desktop
+
+Build the fully local Claude Desktop extension with `npm run pack:claude`, then install `dist/hold-your-voice.mcpb` from **Settings → Extensions → Advanced settings → Install Extension**. The extension accepts text and portable profile JSON in the current conversation only. It does not read or write files, make network requests, or retain writing. See the [Claude Desktop guide](docs/CLAUDE-DESKTOP.md).
+
+### Use it in Claude Code
+
+Hold Your Voice is also a free Claude Code plugin. It starts the same local MCP server through the public npm package; drafts, samples, and profiles stay on your machine.
+
+```text
+/plugin marketplace add shashank-sn/holdyourvoice
+/plugin install hold-your-voice@hold-your-voice
+```
+
+It requires Node.js 20 or newer and npm. See the [Claude Code guide](docs/CLAUDE-CODE.md).
+
 ### Build a local VoiceDNA profile
 
 ```bash

package/dist/cli.js

@@ -2,43 +2,14 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { rules, RULESET_VERSION } from './ai-editor.js';
 import { analyze, rewritePrompt, verify } from './pipeline.js';
+import { parseProfile } from './profile.js';
 import { buildProfile } from './voice-dna.js';
-const usage = 'Commands: profile, analyze, rewrite-prompt, verify, patterns';
+const usage = 'Commands: profile, analyze, rewrite-prompt, verify, patterns, mcp';
 function input(path) {
     return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
 }
-function isNumberRecord(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype)
-        return false;
-    return Object.values(value).every((item) => typeof item === 'number' && Number.isFinite(item));
-}
-function isPunctuation(value) {
-    const marks = ['!', '?', ';', ':', '—'];
-    return isNumberRecord(value) && Object.values(value).every((item) => item >= 0) && Object.keys(value).length === marks.length && marks.every((mark) => mark in value);
-}
-function isMetrics(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const metrics = value;
-    const numbers = [metrics.sentenceLength, metrics.sentenceVariation, metrics.rhythm, metrics.paragraphLength, metrics.lexicalDensity, metrics.questionRate];
-    const stringArrays = [metrics.sentenceStructure, metrics.openingMoves, metrics.vocabulary, metrics.transitions];
-    return numbers.every((item) => typeof item === 'number' && Number.isFinite(item) && item >= 0)
-        && typeof metrics.lexicalDensity === 'number' && metrics.lexicalDensity <= 1
-        && typeof metrics.questionRate === 'number' && metrics.questionRate <= 1
-        && ['first_person', 'second_person', 'third_person', 'mixed'].includes(metrics.pointOfView ?? '')
-        && ['lowercase', 'standard', 'mixed'].includes(metrics.caseStyle ?? '')
-        && stringArrays.every((items) => Array.isArray(items) && items.every((item) => typeof item === 'string'))
-        && isPunctuation(metrics.punctuation);
-}
 function readProfile(path) {
-    const value = JSON.parse(input(path));
-    if (!value || typeof value !== 'object')
-        throw new Error('Profile must be a JSON object.');
-    const profile = value;
-    if (profile.version !== '2' || typeof profile.sampleCount !== 'number' || !Number.isInteger(profile.sampleCount) || profile.sampleCount < 2 || !isMetrics(profile.metrics) || !Array.isArray(profile.avoid) || !profile.avoid.every((item) => typeof item === 'string' && item.trim().length > 0)) {
-        throw new Error('Profile is not a valid Hold Your Voice version 2 profile. Rebuild it with the profile command.');
-    }
-    return profile;
+    return parseProfile(JSON.parse(input(path)));
 }
 function json(value) {
     console.log(JSON.stringify(value, null, 2));
@@ -62,7 +33,7 @@ function profileArguments(args) {
         throw new Error('Usage: hyv profile profile.json sample-a.md sample-b.md [sample-c.md] [--avoid=phrase]');
     return { output, samples, avoid };
 }
-export function runCli(args) {
+export async function runCli(args) {
     const [command, ...rest] = args;
     if (command === 'profile') {
         const { output, samples, avoid } = profileArguments(rest);
@@ -95,12 +66,20 @@ export function runCli(args) {
         json({ version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) });
         return 0;
     }
+    if (command === 'mcp') {
+        if (rest.length > 0)
+            throw new Error('Usage: hyv mcp');
+        await import('./mcp.js');
+        return 0;
+    }
     throw new Error(`${usage}.`);
 }
-try {
-    process.exitCode = runCli(process.argv.slice(2));
-}
-catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-}
+void (async () => {
+    try {
+        process.exitCode = await runCli(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+})();

package/dist/cli.test.js

@@ -44,6 +44,7 @@ test('uses exit code 2 for a failed candidate gate and 1 for misuse', () => {
         assert.equal(verification.status, 2);
         assert.deepEqual(Object.keys(JSON.parse(verification.stdout)).sort(), ['candidate', 'original', 'passed', 'preservationScore', 'regressions', 'version']);
         assert.equal(run('unknown-command').status, 1);
+        assert.equal(run('mcp', 'unexpected').status, 1);
     }
     finally {
         rmSync(directory, { recursive: true, force: true });

package/dist/mcp-tools.js

@@ -0,0 +1,27 @@
+import { rules, RULESET_VERSION } from './ai-editor.js';
+import { analyze, rewritePrompt, verify } from './pipeline.js';
+import { parseProfile } from './profile.js';
+import { buildProfile } from './voice-dna.js';
+function profileFromJson(profileJson) {
+    try {
+        return parseProfile(JSON.parse(profileJson));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error ? error.message : 'Profile is not valid JSON.');
+    }
+}
+export function buildProfileForMcp(samples, avoid = []) {
+    return buildProfile(samples, avoid);
+}
+export function analyzeForMcp(draft, profileJson) {
+    return analyze(draft, profileFromJson(profileJson));
+}
+export function rewritePromptForMcp(draft, profileJson) {
+    return { prompt: rewritePrompt(draft, profileFromJson(profileJson)) };
+}
+export function verifyForMcp(original, candidate, profileJson) {
+    return verify(original, candidate, profileFromJson(profileJson));
+}
+export function patternsForMcp() {
+    return { version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) };
+}

package/dist/mcp-tools.test.js

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { analyzeForMcp, buildProfileForMcp, patternsForMcp, rewritePromptForMcp, verifyForMcp } from './mcp-tools.js';
+const profile = buildProfileForMcp(['I write clearly. I keep the useful detail.', 'I make the call. Then I explain the trade-off.'], ['leverage']);
+const profileJson = JSON.stringify(profile);
+test('builds a portable profile for MCP without files', () => {
+    assert.equal(profile.version, '2');
+    assert.equal(profile.sampleCount, 2);
+});
+test('keeps the dual-engine analysis shape through MCP tools', () => {
+    const result = analyzeForMcp('I leverage a clear plan.', profileJson);
+    assert.equal(result.voiceDna.engine, 'voice_dna');
+    assert.equal(result.aiEditor.engine, 'ai_editor');
+});
+test('creates and verifies an editing loop through MCP tools', () => {
+    const brief = rewritePromptForMcp('I leverage a clear plan.', profileJson);
+    const result = verifyForMcp('I make the call.', 'I make the call.', profileJson);
+    assert.match(brief.prompt, /Tier 0/);
+    assert.equal(result.preservationScore, 100);
+});
+test('exposes the executable pattern IDs through MCP tools', () => {
+    assert.ok(patternsForMcp().rules.some((rule) => rule.id === 'ai.leverage'));
+});

package/dist/mcp.js

@@ -0,0 +1,69 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { analyzeForMcp, buildProfileForMcp, patternsForMcp, rewritePromptForMcp, verifyForMcp } from './mcp-tools.js';
+const writing = z.string().min(1).max(100_000);
+const profileJson = z.string().min(1).max(50_000);
+const samples = z.array(writing).min(2).max(20);
+const avoid = z.array(z.string().min(1).max(200)).max(50).optional();
+function json(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+function failure(error) {
+    return { content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }], isError: true };
+}
+const server = new McpServer({ name: 'hold-your-voice', version: '3.0.2' });
+server.registerTool('hyv_build_profile', {
+    description: 'Build a portable VoiceDNA profile from at least two writing samples. The samples stay in memory and are not saved.',
+    inputSchema: { samples, avoid },
+    annotations: { readOnlyHint: true },
+}, async ({ samples: writingSamples, avoid: phrases }) => {
+    try {
+        return json(buildProfileForMcp(writingSamples, phrases));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_analyze', {
+    description: 'Run the separate VoiceDNA and AI Editor checks against a draft using a portable profile JSON string.',
+    inputSchema: { draft: writing, profile_json: profileJson },
+    annotations: { readOnlyHint: true },
+}, async ({ draft, profile_json }) => {
+    try {
+        return json(analyzeForMcp(draft, profile_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_rewrite_prompt', {
+    description: 'Create a constrained editing brief. It does not rewrite the draft or call a model.',
+    inputSchema: { draft: writing, profile_json: profileJson },
+    annotations: { readOnlyHint: true },
+}, async ({ draft, profile_json }) => {
+    try {
+        return json(rewritePromptForMcp(draft, profile_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_verify', {
+    description: 'Verify a revised candidate against an original draft and portable profile. Reports regressions and preservation without saving either text.',
+    inputSchema: { original: writing, candidate: writing, profile_json: profileJson },
+    annotations: { readOnlyHint: true },
+}, async ({ original, candidate, profile_json }) => {
+    try {
+        return json(verifyForMcp(original, candidate, profile_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_patterns', {
+    description: 'List the exact AI Editor rules that run in this extension.',
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => json(patternsForMcp()));
+await server.connect(new StdioServerTransport());

package/dist/mcp.test.js

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import test from 'node:test';
+test('serves the read-only Claude tools over stdio', async () => {
+    const server = spawn(process.execPath, [new URL('./cli.js', import.meta.url).pathname, 'mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    server.stdout.on('data', (chunk) => { stdout += chunk; });
+    server.stderr.on('data', (chunk) => { stderr += chunk; });
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} })}\n`);
+    server.stdin.end();
+    const [code] = await once(server, 'close');
+    assert.equal(stderr, '');
+    assert.equal(code, 0);
+    const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
+    const tools = responses.find((response) => response.id === 2)?.result?.tools;
+    assert.deepEqual(tools?.map((tool) => tool.name), ['hyv_build_profile', 'hyv_analyze', 'hyv_rewrite_prompt', 'hyv_verify', 'hyv_patterns']);
+    assert.ok(tools?.every((tool) => tool.annotations?.readOnlyHint));
+});

package/dist/profile.js

@@ -0,0 +1,31 @@
+function isNumberRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+        && Object.values(value).every((item) => typeof item === 'number' && Number.isFinite(item));
+}
+function isPunctuation(value) {
+    const marks = ['!', '?', ';', ':', '—'];
+    return isNumberRecord(value) && Object.values(value).every((item) => item >= 0) && Object.keys(value).length === marks.length && marks.every((mark) => mark in value);
+}
+function isMetrics(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const metrics = value;
+    const numbers = [metrics.sentenceLength, metrics.sentenceVariation, metrics.rhythm, metrics.paragraphLength, metrics.lexicalDensity, metrics.questionRate];
+    const stringArrays = [metrics.sentenceStructure, metrics.openingMoves, metrics.vocabulary, metrics.transitions];
+    return numbers.every((item) => typeof item === 'number' && Number.isFinite(item) && item >= 0)
+        && typeof metrics.lexicalDensity === 'number' && metrics.lexicalDensity <= 1
+        && typeof metrics.questionRate === 'number' && metrics.questionRate <= 1
+        && ['first_person', 'second_person', 'third_person', 'mixed'].includes(metrics.pointOfView ?? '')
+        && ['lowercase', 'standard', 'mixed'].includes(metrics.caseStyle ?? '')
+        && stringArrays.every((items) => Array.isArray(items) && items.every((item) => typeof item === 'string'))
+        && isPunctuation(metrics.punctuation);
+}
+export function parseProfile(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('Profile must be a JSON object.');
+    const profile = value;
+    if (profile.version !== '2' || typeof profile.sampleCount !== 'number' || !Number.isInteger(profile.sampleCount) || profile.sampleCount < 2 || !isMetrics(profile.metrics) || !Array.isArray(profile.avoid) || !profile.avoid.every((item) => typeof item === 'string' && item.trim().length > 0)) {
+        throw new Error('Profile is not a valid Hold Your Voice version 2 profile. Rebuild it with the profile command.');
+    }
+    return profile;
+}

package/dist/release-audit.test.js

@@ -8,7 +8,15 @@ const audit = new URL('../scripts/release-audit.mjs', import.meta.url).pathname;
 function fixture(files) {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-audit-'));
     execFileSync('git', ['init', '--quiet'], { cwd: directory });
-    for (const [file, text] of Object.entries(files)) {
+    const defaults = {
+        'package.json': JSON.stringify({ license: 'MIT', files: ['LICENSE'] }),
+        LICENSE: [
+            'Permission is hereby granted, free of charge, to any person obtaining a copy',
+            'The above copyright notice and this permission notice shall be included in all',
+            'THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND',
+        ].join('\n'),
+    };
+    for (const [file, text] of Object.entries({ ...defaults, ...files })) {
         const path = join(directory, file);
         mkdirSync(dirname(path), { recursive: true });
         writeFileSync(path, text);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "A local-first dual-engine writing gate that protects voice and catches generic AI patterns.",
   "type": "module",
   "bin": { "hyv": "dist/cli.js" },
   "files": ["dist", "Readme.md", "LICENSE"],
-  "scripts": { "build": "tsc -p tsconfig.json", "test": "npm run build && node --test dist/**/*.test.js", "check:release": "node scripts/release-audit.mjs", "prepack": "npm run check:release && npm test" },
+  "scripts": { "build": "tsc -p tsconfig.json", "bundle:claude": "esbuild src/mcp.ts --bundle --platform=node --format=esm --target=node20 --outfile=mcpb/server/index.js", "build:claude": "npm run build && npm run bundle:claude", "pack:claude": "npm run build:claude && node scripts/pack-claude.mjs", "test": "npm run build && node --test dist/**/*.test.js", "check:release": "node scripts/release-audit.mjs", "prepack": "npm run check:release && npm test" },
   "engines": { "node": ">=20" },
   "license": "MIT",
   "keywords": ["ai-writing", "cli", "editing", "voice", "writing"],
@@ -13,5 +13,6 @@
   "bugs": { "url": "https://github.com/shashank-sn/holdyourvoice/issues" },
   "homepage": "https://github.com/shashank-sn/holdyourvoice#readme",
   "publishConfig": { "access": "public" },
-  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.7.0" }
+  "devDependencies": { "@types/node": "^22.0.0", "@types/yazl": "^3.3.1", "esbuild": "^0.28.1", "typescript": "^5.7.0", "yazl": "^3.3.1" },
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.30.0", "zod": "^4.4.3" }
 }