Firstory MCP: Character Consistency AI Server

A standalone Model Context Protocol (MCP) server that provides character consistency analysis for fiction writers.

Firstory MCP is a Model Context Protocol server designed to work with Claude Desktop, ChatGPT, and other MCP-compatible clients. It helps fiction writers maintain authentic character voices and consistent behavior patterns throughout their narratives.

Note: This is a standalone MCP server application. It is not related to any separate "Firstory" application.

Quick Install

npx firstory-mcp    # starts the MCP server on http://localhost:3000

Features

• Character Profile Management - Build detailed profiles with personality traits, dialogue patterns, and background
• Consistency Validation - Real-time checks for dialogue, actions, and narrative against established character profiles
• Language-Aware - Supports English and Chinese text via Gemini's native multilingual model; character profiles include an optional languagePreference field
• Client-Mediated Skill Workflow - Firstory Chapter Doctor uses the active AI client for judgment and Firstory MCP for profile/annotation data routing
• Smart Suggestions - AI-powered recommendations for improving character consistency
• Consistency Scoring - Track character consistency metrics over time
• Payment Processing - Stripe-powered Pro tier with one-time $9 purchase

Quick Start (use the hosted MCP)

Most users connect to the remote server. No clone or local API keys are required in your MCP client.

Endpoint: https://firstory-mcp.vercel.app/mcp

Claude / Cursor / other MCP clients

{
  "mcpServers": {
    "firstory-mcp": {
      "url": "https://firstory-mcp.vercel.app/mcp"
    }
  }
}

Complete OAuth when the client prompts you. Then call account-status, register characters with upsert-character, and analyze with character-query.

| Resource | Purpose | |----------|---------| | agent-setup.md | Agent-oriented install + tool list | | llms.txt | Machine-readable index | | mcp.json.example | Copy-paste MCP client config | | API Reference | All 9 tools and auth policy | | Deployment / OAuth | Redirect URLs and troubleshooting |

Verify the endpoint (no auth):

curl -sS https://firstory-mcp.vercel.app/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Local development (contributors)

• Node.js 22.13.0 or later, pnpm 10.x (corepack enable)
• Copy .env.example to .env.local and set Supabase + embedding keys

git clone https://github.com/clchinkc/firstory-mcp.git
cd firstory-mcp
pnpm install
pnpm run dev

Server: http://localhost:3000/mcp

pnpm test
pnpm run lint
pnpm run build
pnpm run launch:check

Documentation

| Documentation | Purpose | |---|---| | Docs Index | Source-of-truth map for implementation and operations docs | | Deployment Guide | Deploy to Vercel with Supabase authentication | | Quick Start Guide | Using Firstory MCP with Claude | | API Reference | Tool definitions and examples | | agent-setup.md | Remote install for coding agents | | llms.txt | Machine-readable tool and env index | | Launch Checklist | Pre-launch verification | | Performance & launch checks | pnpm run launch:check, complexity scanner, hot-path index | | Monetization Runbook | Stripe setup, buyer journey, and pricing experiments | | API — handler runtime | createMcpRuntime, engine cache, hooks, embeddings | | Architecture ADRs | Transport, HookRegistry, schema decisions | | Contributing | How to contribute |

Project Structure

├── api/                         # Vercel serverless functions
│   ├── mcp.ts                   # MCP endpoint (deployed)
│   ├── cron/                    # QStash retry + reconciliation cron
│   └── webhooks/stripe.ts       # Stripe ingress (signature + enqueue)
├── packages/
│   └── @firstory/
│       └── embeddings/          # @firstory/embeddings — Gemini/OpenRouter embeddings
├── src/
│   ├── mcp-server/              # MCP handler, runtime bootstrap (local dev)
│   ├── skills/payments/         # Stripe, webhook queue, email, reconciliation
│   ├── api/routes/webhooks.ts   # Express /webhooks/stripe (local dev)
│   ├── api/middleware/          # Auth + Supabase DB adapter
│   └── app/                     # React MCP App frontend
├── tests/
│   ├── payments-reliability/    # Webhook queue + QStash + billing reliability
│   └── integration/             # Cross-module integration tests
├── docs/guides/                 # Operational docs (API, deployment, observability)
├── @types/                      # Shared ambient types (e.g. Express augmentation)
├── database/schema.sql           # Supabase Postgres schema
├── supabase/migrations/          # Idempotent Supabase migrations
├── components.json              # shadcn/ui config (MCP App)
├── tsconfig.app.json            # TypeScript project for src/app only
├── package.json
└── vercel.json                 # Vercel routing + cron config

Development Workflow

Making Changes

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes and write tests
3. Lint and test: pnpm run lint && pnpm test
4. Commit with clear messages: git commit -m "feat: description"
5. Push and create a pull request

Available Scripts

| Command | Purpose | |---|---| | pnpm run dev | Start server in watch mode | | pnpm run typecheck | Run full typecheck (server + app) | | pnpm run typecheck:server | Typecheck server code only | | pnpm run typecheck:app | Typecheck React app only | | pnpm run lint | Lint source, API, and tests | | pnpm test | Run tests once | | pnpm run build | Build embeddings package, server (build/server), and app (dist) | | pnpm run build:embeddings | Build @firstory/embeddings only | | pnpm start | Start production server from build/server | | pnpm run launch:check | Check direct-install launch readiness | | pnpm run launch:check:env | Check launch readiness with required production env vars |

CI/CD Pipeline

GitHub Actions (ci.yml) runs on every push with pnpm (pnpm install --frozen-lockfile):

• Lint — ESLint
• Test — Vitest
• Build — full TypeScript typecheck (server + MCP App) and production build

develop is the default integration branch. main is the Vercel production branch; merge the develop → main release PR when you are ready to publicize the MCP.

MCP Server

Endpoint: https://firstory-mcp.vercel.app/mcp

Public pages:

• Landing page: https://firstory-mcp.vercel.app/
• Privacy policy: https://firstory-mcp.vercel.app/privacy
• Terms: https://firstory-mcp.vercel.app/terms
• Direct install endpoint: https://firstory-mcp.vercel.app/mcp

OAuth behavior (authoritative details: docs/guides/API.md + docs/guides/MCP-Deployment.md):

• Lifecycle/discovery requests (initialize, tools/list, resources/list, resources/read) are allowed without auth.
• tools/call for account-status is allowed without auth (anonymous tier preview).
• All other tools/call operations require OAuth bearer auth, including character tools (character-query, character-list, character-profile, upsert-character, trigger-analysis, feedback-character) and billing tools (create-checkout-session, create-billing-portal-session). Unauthenticated calls return 401 with WWW-Authenticate and resource_metadata.
• Protected resource metadata is published at:
  • /.well-known/oauth-protected-resource
  • /.well-known/oauth-protected-resource/mcp
• OAuth authorization server discovery is published at:
  • /.well-known/oauth-authorization-server
  • /.well-known/openid-configuration

Canonical tool contracts, auth policy, and REST integration surface live in docs/guides/API.md.

Usage

1. Register a character — give them a name, traits, and behavioral rules:

Use the `upsert-character` tool with a character profile like:
{
  "id": "sarah-001",
  "name": "Sarah",
  "aliases": ["Sar"],
  "role": "protagonist",
  "traits": [
    {
      "name": "temperament",
      "value": "brave, self-doubting, protective of her brother",
      "sources": ["profile"],
      "confidence": 1
    }
  ],
  "voice": {
    "sentenceLengthRange": [4, 12],
    "register": "casual",
    "patterns": ["short sentences when scared", "uses humor to deflect"],
    "languagePreference": "english"
  },
  "relationships": [
    {
      "targetCharacterId": "marcus-001",
      "type": "family",
      "description": "Protective but competitive older sister",
      "trajectory": "developing"
    }
  ],
  "arc": "Learns to trust other people with responsibility.",
  "notes": []
}

2. Check consistency — paste dialogue or a scene, get feedback on whether it matches the character:

Use `character-query` with the character name and the text to analyze.

3. Run scene checks — analyze newly written passages for trait, voice, behavior, and relationship consistency.

4. Improve memory — after reviewing issues, call feedback-character with accept or reject so the next analysis uses updated characterMemory.

See MCP App Developer Quickstart for the MCP App UI integration, including writer review actions and the hosted Stripe checkout flow.

Project Resources

• 📋 Task Tracking: Linear Workspace
• 📚 Architecture: See docs/architecture/
• 🤖 Claude Integration: See .claude/ for AI workflow guidelines

Status

Production: https://firstory-mcp.vercel.app/mcp — Live and operational.

• ✅ 9 MCP tools (character analysis, profile upsert, feedback learning, account/billing)
• ✅ Statistical anomaly detection (no hardcoded word lists)
• ✅ Parallelized scene-level consistency checks + capped embedding concurrency
• ✅ Real-time learned character memory from writer feedback
• ✅ Per-user authentication via Supabase
• ✅ Tier-gated features (free/pro)
• ✅ Incremental MCP app progress tracking in heatmap/session timeline
• ✅ Production Vite bundle for the embedded MCP App
• ✅ Polished UI/UX — Tailwind v4 + shadcn/ui design system with layered shadows and consistent token-driven styling.
• ✅ Deployed to Vercel with automatic CI/CD

See the architecture docs to get started.

Support & Contributing

• Bugs and feature requests: GitHub Issues
• Billing/privacy/deletion: contact details on your Stripe receipt, or open a private issue if you prefer not to post account identifiers publicly.
• 🤝 Contributing: CONTRIBUTING.md (branch from develop, PR to develop)

License

MIT - See LICENSE for details.

Authors

Built with ❤️ for fiction writers everywhere.

Status: Active Development | Latest Release: v0.1.0