InkQuest

dev.inkquestPublished by inkquest.devOfficial publisherv1.0.0Updated Oct 25, 2026

Browse free InkQuest stories, openings, and HSK recommendations.

VerifiedStreamable HTTPWeb executableKnowledge & MemoryMedia & Design

Overview

AI-generated overview

A read-only remote MCP server that lets an assistant browse free InkQuest language-learning stories, read their opening scenes, and get HSK-leveled story picks.

What you can do
List free public stories with title, level (HSK or CEFR), genre, description and reading link, filterable by language, HSK level and genre. Retrieve the free opening scene of a story, with pinyin or pronunciation and short glosses where available, plus the opening choices. Recommend up to three stories ranked by HSK band, genre or interest keywords and target language, each with a short reason.
When to use it
Useful when someone wants Chinese or English reading practice material at a given HSK or CEFR level, or wants a story recommendation with a link to read it. It is a browsing and recommendation aid, not a full reading or account tool.
Requirements
A remote Streamable HTTP endpoint at inkquest.dev; no authentication, environment variables or headers are declared. Network access to the endpoint is needed.
Before you install
Read-only and limited to free public catalog content: generated stories and premium scenes are not exposed, and premium choices are labeled with their following scenes omitted. No credentials are requested by the MCP endpoint.

Installation

In SourceWeft

  1. Open InkQuest in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/dev.inkquest%2Finkquest/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "inkquest": {
      "type": "http",
      "url": "https://inkquest.dev/api/mcp"
    }
  }
}

README

InkQuest

Interactive language-learning fiction built with Next.js, Supabase, and OpenNext Cloudflare.

Getting Started

Install dependencies and run the development server:

bash
pnpm installpnpm dev

Open http://localhost:3000.

Generated Stories Foundation

The first cloud-generation foundation includes:

  • Supabase credit ledger, reservations, story graph, jobs, outbox, billing tables, and RLS in supabase/migrations/202608220001_generated_story_billing.sql.
  • Server-created Lemon Squeezy checkouts and idempotent webhook processing.
  • Authenticated quote and generated-story job creation APIs.
  • Cloud adapter contracts and a reusable scene enrichment core in tools/story-pipeline/src/core.

Required server environment variables:

text
NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEYNEXT_PUBLIC_GOOGLE_CLIENT_IDSUPABASE_SERVICE_ROLE_KEYNEXT_PUBLIC_SITE_URL
LEMONSQUEEZY_API_KEYLEMONSQUEEZY_STORE_IDLEMONSQUEEZY_WEBHOOK_SECRETLEMONSQUEEZY_SUBSCRIPTION_VARIANT_IDLEMONSQUEEZY_SUBSCRIPTION_CREDIT_GRANTLEMONSQUEEZY_CREDIT_PACK_VARIANT_IDLEMONSQUEEZY_CREDIT_PACK_GRANT
GENERATION_PRICING_VERSIONGENERATION_OPENING_TEXT_CREDITSGENERATION_OPENING_TTS_CREDITSGENERATION_SCENE_TEXT_CREDITSGENERATION_SCENE_TTS_CREDITS

NEXT_PUBLIC_GOOGLE_CLIENT_ID is the Web OAuth client ID from Google Cloud. Add each deployed site origin (including local development) to its authorized JavaScript origins, and enable Google provider in Supabase.

Credit-pack variables are optional until that product is enabled. Generation pricing falls back to 20 credits for opening text, 10 for opening TTS, 12 for scene text, and 6 for scene TTS when the corresponding environment variables are missing or invalid. TTS pricing is required only when every_scene is offered. Never expose the service-role key, Lemon API key, or webhook secret through a NEXT_PUBLIC_ variable.

Apply the migrations in filename order. Existing environments that already ran the first two migrations should next apply supabase/migrations/202608230001_generated_story_tts.sql; it creates the private audio bucket and adds independent TTS commit/retry/refund transactions.

The generation execution path is:

text
Next.js → inkquest-generation Queue → generation-dispatcher → Cloud Run story-pipeline Worker

Additional main-app variables:

text
GENERATION_DISPATCH_SECRETGENERATED_AUDIO_BUCKET

Cloud Run Worker variables:

text
SUPABASE_URLSUPABASE_SERVICE_ROLE_KEYGENERATION_WORKER_TOKENLLM_CHAT_COMPLETIONS_URLLLM_API_KEYLLM_MODELLLM_PROMPT_VERSIONTENCENT_SECRET_IDTENCENT_SECRET_KEYTENCENT_REGIONTENCENT_TTS_VOICEAZURE_SPEECH_KEYAZURE_SPEECH_REGIONAZURE_TTS_VOICE_ZHAZURE_TTS_VOICE_ENSTORY_TTS_ZH_PROVIDERSTORY_TTS_EN_PROVIDERGENERATED_AUDIO_BUCKET

GENERATED_AUDIO_BUCKET defaults to generated-audio. Configure the Azure Speech key and region on the Cloud Run Worker; the verified evaluation resource uses eastasia. Azure is preferred for both Chinese and English when configured, with zh-CN-Xiaoxiao:DragonHDFlashLatestNeural and en-US-JennyNeural as defaults. Set STORY_TTS_ZH_PROVIDER or STORY_TTS_EN_PROVIDER to azure or tencent to override selection. The Worker image also installs FFmpeg to normalize multi-part Tencent audio into one seekable MP3 before upload.

Create inkquest-generation and inkquest-generation-dlq in Cloudflare, deploy the main app, then deploy tools/generation-dispatcher/wrangler.jsonc. Configure GENERATION_WORKER_URL on the dispatcher and store GENERATION_WORKER_TOKEN with wrangler secret put.

For local development, start the Worker in a separate terminal before generating a story:

bash
PORT=8080 pnpm --filter @inkquest/story-pipeline worker:start

The Next.js development server dispatches new jobs to http://127.0.0.1:8080 by default. Set GENERATION_WORKER_URL to override it, and make sure Next.js and the Worker use the same GENERATION_WORKER_TOKEN.

Call POST /api/internal/generation/outbox every minute with Authorization: Bearer <GENERATION_DISPATCH_SECRET> to recover failed queue publications and expired Worker leases.

MCP

A read-only Model Context Protocol server for the public story catalog is served at /api/mcp (Streamable HTTP). It lists free stories, returns the opening scene, and recommends matches, each with an https://inkquest.dev/stories/{id} link. It does not expose generated stories or premium scenes. Setup, local checks, and registry publishing are in docs/mcp.md.

Validation

bash
pnpm exec tsc --noEmitpnpm --filter @inkquest/story-pipeline typecheckpnpm lintpnpm build

Deployment uses OpenNext Cloudflare; see wrangler.jsonc and the preview / deploy scripts in package.json.

Source: README.md at commit e941122

Tools

3

list_stories

List public stories

List free, public InkQuest stories. Each card has the title, level (HSK for Chinese, CEFR for English), genre, a short description, and the public reading URL https://inkquest.dev/stories/{id}. Optional filters: target_language (zh or en), hsk_level (Chinese stories only), and genre. Does not include subscriber-only scenes, withdrawn demos, or user-generated stories.

Parametersgenrehsk_leveltarget_language

get_story_opening

Get the free opening

Return the free opening scene of one public InkQuest story: plain text, pinyin or pronunciation and short glosses when the catalog has them, and the opening choices. Premium choices are labeled and their following scenes are omitted. Always includes the https://inkquest.dev/stories/{id} URL where the reader continues. Refuses unknown ids, withdrawn demos, locked stories, and user-generated stories. Never returns subscriber-only scene text.

Parametersstory_idrequired

recommend_story

Recommend a public story

Recommend up to three public InkQuest stories. Pass hsk_level (1-9 or "HSK 4") to rank Chinese stories by closeness to that band. Optional genre or interests (keywords such as mystery, romance, xianxia, sci-fi) boost matches. Optional target_language is zh or en. Each match includes a short reason and a https://inkquest.dev/stories/{id} link. Only free catalog stories are considered; subscriber-only scenes and user-generated stories are excluded.

Parametersgenrehsk_levelintereststarget_language

Version history

1
  1. v1.0.0LatestOct 15, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.