My Voice

my-voice-mcp is a local-first MCP server that builds compact voice profiles from writing samples, then compares, rewrites, or generates new text in that voice.

The current primary workflow is a process-first formal email flow:

• create a bundled voice profile from multiple curated email samples
• rewrite existing text in that voice
• generate new text in that voice
• compare fast versus reviewed quality modes with a fixed human review set

Current MVP surface

• voice_create_profile for legacy single-PDF profile creation
• voice_create_profile_bundle for preferred multi-sample formal email profile creation
• voice_compare_text
• voice_rewrite_text
• voice_generate_text
• voice_list_profiles
• voice_get_profile
• voice_delete_profile
• voice_validate_source

voice_rewrite_text and voice_generate_text support:

• qualityMode: "fast"
• qualityMode: "reviewed"

reviewed mode uses one internal draft -> critique -> revise loop when a model-backed provider is available. If the server is running in heuristic mode, it falls back to fast.

What is implemented

• TypeScript MCP server on Node 20+
• stdio and Streamable HTTP transports from one codebase
• bearer-token HTTP auth with optional localhost dev bypass
• local filesystem profile storage
• single-PDF heuristic profile path
• bundled email-formal profile path with:
  • at least 3 samples required
  • email normalization for greetings, signatures, and reply metadata
  • provenance capture
  • stable versus topic-specific marker separation
  • model-backed distillation with heuristic fallback
• provider adapters for:
  • heuristic
  • OpenAI-compatible HTTP
  • Ollama
  • AWS Bedrock
• evaluation harness under evals/email-formal

Quick start

1. Install dependencies

npm install --no-audit --no-fund

2. Build and test

npm run build
npm test

3. Run the email-formal evaluation harness

npm run eval:email-formal

This writes review artifacts to evals/email-formal/output/.

4. Start the MCP server

npm run start:stdio

or

npm run start:http

HTTP endpoints:

• POST /mcp
• GET /healthz

Provider and Endpoint Setup

This repo has three provider paths in code today:

• openai-compatible
• ollama
• bedrock

That distinction matters:

• openai-compatible means any endpoint that accepts OpenAI-style chat completions with a baseUrl, bearer token, and model name
• ollama is the first-class local-model path already implemented in this repo
• bedrock is also an explicit provider path already implemented in this repo

Support status

Implemented in code:

• openai-compatible
• ollama
• bedrock

Documented compatibility candidates through the generic openai-compatible adapter:

• Gemini via Google's OpenAI compatibility endpoint
• Claude via Anthropic's OpenAI SDK compatibility endpoint

Validated on this machine:

• heuristic fallback
• local build, test, and email-formal eval harness

Not yet validated on this machine:

• live model-backed reviewed mode
• live Ollama-backed runs
• live Gemini-backed or Claude-backed compatibility runs

Generic OpenAI-compatible endpoint

Use this when your provider exposes an OpenAI-style chat completions API.

$env:MY_VOICE_PROVIDER="openai-compatible"
$env:MY_VOICE_BASE_URL="https://your-endpoint.example/v1"
$env:MY_VOICE_MODEL="your-model"
$env:MY_VOICE_API_KEY="your-token"

Gemini through the OpenAI-compatible adapter

This repo does not have a native Gemini provider. Use the existing openai-compatible adapter.

$env:MY_VOICE_PROVIDER="openai-compatible"
$env:MY_VOICE_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
$env:MY_VOICE_MODEL="gemini-3.5-flash"
$env:MY_VOICE_API_KEY="<your-gemini-api-key>"

Claude through the OpenAI-compatible adapter

This repo does not have a native Claude provider. Use the existing openai-compatible adapter.

$env:MY_VOICE_PROVIDER="openai-compatible"
$env:MY_VOICE_BASE_URL="https://api.anthropic.com/v1/"
$env:MY_VOICE_MODEL="claude-sonnet-4-5"
$env:MY_VOICE_API_KEY="<your-claude-api-key>"

Anthropic describes this as an OpenAI SDK compatibility layer rather than the full native Claude API surface, so it is useful for compatibility testing but should not be documented as first-class native support in this repo.

Ollama as the first-class local runtime

Use this when you want the simplest local-model path currently supported by the repo.

$env:MY_VOICE_PROVIDER="ollama"
$env:MY_VOICE_BASE_URL="http://localhost:11434"
$env:MY_VOICE_MODEL="qwen3-coder"

Other locally hosted OpenAI-compatible servers

If you run another local server that exposes an OpenAI-style endpoint, keep the provider as openai-compatible and point MY_VOICE_BASE_URL to that local server.

$env:MY_VOICE_PROVIDER="openai-compatible"
$env:MY_VOICE_BASE_URL="http://127.0.0.1:8000/v1"
$env:MY_VOICE_MODEL="your-local-model"
$env:MY_VOICE_API_KEY="not-needed-or-local-token"

Bedrock: native provider path vs OpenAI-compatible endpoint

This repo already has a native bedrock provider path:

$env:MY_VOICE_PROVIDER="bedrock"
$env:MY_VOICE_MODEL="<bedrock-model-id>"
$env:MY_VOICE_BEDROCK_REGION="us-east-1"

Amazon Bedrock also offers OpenAI-compatible APIs. If you want to use that route instead, treat it as openai-compatible rather than bedrock:

$env:MY_VOICE_PROVIDER="openai-compatible"
$env:MY_VOICE_BASE_URL="https://bedrock-mantle.us-east-1.api.aws/v1"
$env:MY_VOICE_MODEL="<bedrock-openai-compatible-model>"
$env:MY_VOICE_API_KEY="<bedrock-api-key>"

Local LLM Setup

Recommended local path: Ollama

1. Install Ollama on the machine where my-voice-mcp will run.
2. Pull a model:

ollama pull qwen3-coder

3. Confirm the service is up:

curl http://localhost:11434/api/tags

4. Set env vars:

$env:MY_VOICE_PROVIDER="ollama"
$env:MY_VOICE_BASE_URL="http://localhost:11434"
$env:MY_VOICE_MODEL="qwen3-coder"

5. Build and start:

npm.cmd run build
node dist/index.js stdio

6. Run one rewrite or generate smoke test through your MCP client.

Advanced local path: another OpenAI-compatible server

1. Start your local server and confirm its OpenAI-style base URL.
2. Confirm the endpoint responds:

curl http://127.0.0.1:8000/v1/models

3. Set env vars:

$env:MY_VOICE_PROVIDER="openai-compatible"
$env:MY_VOICE_BASE_URL="http://127.0.0.1:8000/v1"
$env:MY_VOICE_MODEL="your-local-model"
$env:MY_VOICE_API_KEY="local-token-or-placeholder"

4. Build, start, and run one smoke test through the MCP tool flow.

Environment

• MY_VOICE_PROVIDER: none, ollama, openai-compatible, or bedrock
• MY_VOICE_MODEL: model name or ID
• MY_VOICE_BASE_URL: provider base URL for Ollama or OpenAI-compatible APIs
• MY_VOICE_API_KEY: bearer token for OpenAI-compatible providers
• MY_VOICE_BEDROCK_REGION: AWS region for Bedrock
• MY_VOICE_HTTP_BEARER_TOKEN: token required for HTTP MCP access
• MY_VOICE_HTTP_ALLOW_UNAUTH_LOCALHOST: allow localhost HTTP calls without a bearer token
• MY_VOICE_DATA_DIR: local profile storage directory
• MY_VOICE_MAX_SOURCE_CHARS: hard character cap for extracted source text
• MY_VOICE_MAX_SOURCE_TOKENS: hard token estimate cap for extracted source text

Storage layout

Profiles are stored under profiles/ by default:

profiles/
  index.json
  <voiceId>/
    extracted.txt
    guide.json
    guide.md
    source.pdf                  # legacy single-PDF profiles only
    bundle-sources.json         # bundled profiles only
    samples/                    # bundled profiles only
      01-<sample>.txt
      02-<sample>.txt

Evaluation set

The current review harness lives in evals/email-formal/ and includes:

• 4 bundled source samples
• 3 rewrite cases
• 3 prompt-to-draft generation cases
• a human review rubric

Use this to compare fast and reviewed output before claiming process quality.

Setup guides

• Requirements and decision log: REQUIREMENTS.md
• Active checklist: TODO.md
• Step-by-step testing and MCP client setup: TESTING.md
• Future long-form fiction handoff: NOVEL_VOICE_BOOTSTRAP.md

Reference docs

• Gemini OpenAI compatibility: Google AI for Developers
• Claude OpenAI SDK compatibility: Anthropic
• Bedrock OpenAI-compatible APIs: AWS API compatibility
• Bedrock Mantle endpoint: AWS Responses API docs