@jinshuju/mcp 0.0.0-stage → 0.3.0

package/dist/app.js

@@ -0,0 +1,224 @@
+/**
+ * HTTP entry (Hono): the same app runs on Node (node.ts) and Cloudflare Workers (worker.ts).
+ *
+ *   GET  /                                    landing page
+ *   GET  /healthz                             health check
+ *   GET  /.well-known/oauth-protected-resource[/mcp]   RFC 9728, pointing at account.jinshuju.net
+ *   GET  /.well-known/oauth-authorization-server       RFC 8414 mirror (for older clients that probe only the resource domain)
+ *   POST /mcp                                 MCP Streamable HTTP (2026-07-28 stateless; the 2025 handshake falls back to stateless)
+ *
+ * The service may sit under a path prefix (e.g. https://host/jinshuju-mcp/…, with the platform stripping the prefix when
+ * forwarding): JINSHUJU_MCP_PUBLIC_URL gives the public address (prefix included; a comma-separated list gives several,
+ * picked by the request's Host, so a custom domain and the platform's default address both work), and resource_metadata in
+ * the 401 challenge points at the well-known document under this service's own path rather than the domain root; RFC 9728
+ * lets clients fetch the URL the challenge gives. When it is not set, the address is inferred from the request (trusting
+ * the reverse proxy's X-Forwarded-*).
+ *
+ * With POSTHOG_API_KEY set, every request's McpServer gets PostHog MCP analytics (analytics.ts), reported in waitUntil after
+ * the response goes out. Unexpected exceptions go to Sentry (worker.ts initializes it with withSentry; without SENTRY_DSN the
+ * SDK sends nothing; the Node entry is not wired): those a tool handler throws, an unreachable API during token verification,
+ * and anything a route does not catch. A 4xx / 5xx from the API is a normal tool result and is not reported.
+ */
+import { Hono } from 'hono';
+import { buildOAuthProtectedResourceMetadata, createMcpHandler, isLegacyRequest, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { captureException, setUser } from '@sentry/cloudflare';
+import { analyticsFromConfig, CONTEXT_INSTRUCTIONS } from './analytics.js';
+import { JinshujuApi, TransportError } from './api.js';
+import { TokenVerifier, bearerToken, challenge, loadAuthServerMetadata, userIdOf } from './auth.js';
+import { DEFAULTS } from './config.js';
+import { StaticCredential } from './credential.js';
+import { buildServer, INSTRUCTIONS, META } from './server.js';
+import { TOOLS } from './tools.js';
+import { SERVER_TITLE, VERSION } from './version.js';
+export const MCP_PATH = '/mcp';
+export function createApp(options = {}) {
+    const cfg = { ...DEFAULTS, ...options.config };
+    const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+    const api = new JinshujuApi({ baseUrl: cfg.apiBaseUrl, fetch: fetchImpl, timeoutMs: cfg.timeoutMs });
+    const verifier = new TokenVerifier({ api, cacheTtlMs: cfg.tokenCacheTtlMs });
+    const analytics = options.analytics === undefined ? analyticsFromConfig(cfg, fetchImpl) : (options.analytics ?? undefined);
+    const instructions = analytics?.collectIntent ? `${INSTRUCTIONS}\n${CONTEXT_INSTRUCTIONS}` : INSTRUCTIONS;
+    let metadata;
+    const authServerMetadata = () => (metadata ??= options.authServerMetadata
+        ? Promise.resolve(options.authServerMetadata)
+        : loadAuthServerMetadata(cfg.authServer, fetchImpl));
+    // One McpServer per request, with the token closed over in every tool handler; analytics is installed per request too,
+    // so the user and session follow the request. The analytics handle is stored per request object: the factory installs
+    // it, and the route takes it out to flush after the response goes out.
+    const trackers = new WeakMap();
+    const factory = async (ctx) => {
+        const token = ctx.authInfo?.token;
+        if (!token)
+            throw new Error('unauthenticated request reached the MCP handler');
+        const server = buildServer({
+            credential: new StaticCredential(token),
+            config: cfg,
+            fetch: fetchImpl,
+            instructions,
+            onToolError: reportToolError
+        });
+        if (analytics && ctx.requestInfo)
+            trackers.set(ctx.requestInfo, await analytics.instrument(server, ctx.authInfo));
+        return server;
+    };
+    // Tools send no progress notifications, so the response is one JSON (the default auto mode): it is assembled after the handler finishes, and this request's analytics is complete before it returns.
+    const handler = createMcpHandler(factory, { legacy: 'reject' });
+    /**
+     * Stateless service for the 2025 handshake (initialize + Mcp-Session-Id). It is wired here instead of using the SDK's
+     * own fallback only to answer with JSON instead of SSE: SSE sends the response headers before the handler runs, so the
+     * Mcp-Session-Id the PostHog SDK mints on initialize (carrying the client name and version, and sent back by the client
+     * on every later request) never reaches the headers, and tool call analytics would land after the response and before
+     * the flush.
+     */
+    async function serveLegacy(request, authInfo) {
+        if (request.method.toUpperCase() !== 'POST')
+            return jsonRpcError(405, -32000, 'Method not allowed.');
+        const server = await factory({ era: 'legacy', authInfo, requestInfo: request });
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true
+        });
+        try {
+            await server.connect(transport);
+            return await transport.handleRequest(request, { authInfo });
+        }
+        catch (error) {
+            console.error('legacy MCP request failed:', error);
+            captureException(error);
+            return jsonRpcError(500, -32603, 'Internal server error.');
+        }
+        finally {
+            transport.close().catch(() => { });
+            server.close().catch(() => { });
+        }
+    }
+    /**
+     * Public base URL (no trailing slash, may include a path prefix). With addresses configured, picks one by the request's
+     * Host, falling back to the first; without, infers it from the request (trusting the reverse proxy's X-Forwarded-*).
+     */
+    const publicUrls = cfg.publicUrls.map((u) => ({ base: u.replace(/\/$/, ''), host: new URL(u).host.toLowerCase() }));
+    function publicBase(request) {
+        const url = new URL(request.url);
+        const host = (request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? url.host)
+            .split(',')[0]
+            .trim();
+        if (publicUrls.length) {
+            const wanted = host.toLowerCase();
+            return (publicUrls.find((u) => u.host === wanted) ?? publicUrls[0]).base;
+        }
+        const proto = request.headers.get('x-forwarded-proto') ?? url.protocol.replace(':', '');
+        const prefix = (request.headers.get('x-forwarded-prefix') ?? '').replace(/\/$/, '');
+        return `${proto}://${host}${prefix}`;
+    }
+    const resourceUrl = (request) => new URL(`${publicBase(request)}${MCP_PATH}`);
+    const resourceMetadataUrl = (request) => `${publicBase(request)}/.well-known/oauth-protected-resource${MCP_PATH}`;
+    const json = (body, status = 200) => new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            'Content-Type': 'application/json',
+            'Cache-Control': 'public, max-age=300',
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Methods': 'GET, OPTIONS',
+            'Access-Control-Allow-Headers': 'mcp-protocol-version'
+        }
+    });
+    // Ignore trailing slashes: users often enter the address as /mcp/, which the default strict matching answers with 404.
+    const app = new Hono({ strict: false });
+    // Exceptions a route does not catch: Hono only logs them to console and answers 500 by default; also report them to Sentry here.
+    app.onError((error, c) => {
+        console.error('unhandled error:', error);
+        captureException(error);
+        return c.text('Internal Server Error', 500);
+    });
+    app.get('/', (c) => c.json({
+        name: SERVER_TITLE,
+        version: VERSION,
+        mcp: resourceUrl(c.req.raw).href,
+        docs: 'https://open.jinshuju.net/mcp',
+        tools: TOOLS.length,
+        generatedFrom: META.generatedFrom
+    }));
+    app.get('/healthz', (c) => c.text('ok'));
+    // RFC 9728 protected resource metadata: the paths with and without /mcp answer the same document (for clients that probe only the origin).
+    const prmPaths = ['/.well-known/oauth-protected-resource', `/.well-known/oauth-protected-resource${MCP_PATH}`];
+    app.on(['GET', 'OPTIONS'], prmPaths, async (c) => {
+        if (c.req.method === 'OPTIONS')
+            return json(null, 204);
+        const metadata = buildOAuthProtectedResourceMetadata({
+            oauthMetadata: await authServerMetadata(),
+            resourceServerUrl: resourceUrl(c.req.raw),
+            resourceName: SERVER_TITLE,
+            serviceDocumentationUrl: new URL('https://open.jinshuju.net/mcp'),
+            scopesSupported: ['public', 'forms', 'read_entries', 'write_entries', 'form_setting', 'users']
+        });
+        return json(metadata);
+    });
+    // RFC 8414 authorization server metadata mirror.
+    app.on(['GET', 'OPTIONS'], '/.well-known/oauth-authorization-server', async (c) => {
+        if (c.req.method === 'OPTIONS')
+            return json(null, 204);
+        return json(await authServerMetadata());
+    });
+    app.all(MCP_PATH, async (c) => {
+        const request = c.req.raw;
+        const prm = resourceMetadataUrl(request);
+        const token = bearerToken(request);
+        if (!token)
+            return challenge(prm, 'Missing or invalid access token');
+        let authInfo;
+        try {
+            authInfo = await verifier.verify(token);
+        }
+        catch (error) {
+            console.error('token verification failed:', error);
+            captureException(error);
+            return new Response(JSON.stringify({
+                error: 'server_error',
+                error_description: 'Cannot verify the token: the Jinshuju API is unreachable for now'
+            }), {
+                status: 503,
+                headers: { 'Content-Type': 'application/json', 'Retry-After': '5' }
+            });
+        }
+        if (!authInfo)
+            return challenge(prm, 'Missing or invalid access token');
+        const userId = userIdOf(authInfo);
+        if (userId)
+            setUser({ id: userId });
+        const response = (await isLegacyRequest(request))
+            ? await serveLegacy(request, authInfo)
+            : await handler.fetch(request, { authInfo });
+        // The API answered 401 during a tool call (the token expired mid-way): make the next request verify again.
+        if (response.status === 401)
+            await verifier.forget(token);
+        const tracker = trackers.get(request);
+        if (tracker)
+            flushInBackground(c, tracker);
+        return response;
+    });
+    return app;
+}
+/** An exception a tool throws: an unreachable API / timeout is environmental and logged as a warning; anything else is our bug. */
+function reportToolError(error, tool) {
+    captureException(error, { tags: { tool }, level: error instanceof TransportError ? 'warning' : 'error' });
+}
+function jsonRpcError(status, code, message) {
+    return new Response(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }), {
+        status,
+        headers: { 'Content-Type': 'application/json' }
+    });
+}
+/** Sends this request's analytics: on Workers it goes into waitUntil and the response does not wait; Node has no executionCtx, so it fires and forgets. */
+function flushInBackground(c, tracker) {
+    const flushing = tracker.flush().catch((error) => {
+        console.error('posthog flush failed:', error);
+        captureException(error, { level: 'warning' });
+    });
+    try {
+        c.executionCtx.waitUntil(flushing);
+    }
+    catch {
+        // Node: no executionCtx; sending already started above
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/auth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Authentication in HTTP mode: this service is only an OAuth Resource Server.
+ *
+ * - The authorization server is account.jinshuju.net (dynamic registration / PKCE / refresh supported); this service
+ *   issues no tokens;
+ * - the request's Bearer (an OAuth token or a personal / account access token) goes to API v1 as is;
+ * - the API decides whether a token is valid: one light call (GET /me) checks it, and the result is cached by token
+ *   hash for a while, so every tool call does not spend an extra API request;
+ * - with no token or an invalid one, answers 401 + WWW-Authenticate: Bearer resource_metadata=..., and the client
+ *   goes through OAuth from there.
+ */
+import { type AuthInfo, type OAuthMetadata } from '@modelcontextprotocol/server';
+import type { JinshujuApi } from './api.js';
+export interface VerifierOptions {
+    api: JinshujuApi;
+    cacheTtlMs: number;
+    maxEntries?: number;
+    now?: () => number;
+}
+/** Token hash: the key of the verification cache, and the source of the analytics session id. */
+export declare function sha256(text: string): Promise<string>;
+export declare class TokenVerifier {
+    private readonly options;
+    private readonly cache;
+    private readonly now;
+    constructor(options: VerifierOptions);
+    /** Returns AuthInfo when valid, undefined when not. A network failure counts as invalid but is not cached. */
+    verify(token: string): Promise<AuthInfo | undefined>;
+    forget(token: string): Promise<void>;
+}
+/** The Jinshuju user id in AuthInfo (the id from GET /me), undefined when no user was identified; analytics and Sentry both identify the user by it. */
+export declare function userIdOf(authInfo: AuthInfo | undefined): string | undefined;
+export declare function bearerToken(request: Request): string | undefined;
+export declare function challenge(resourceMetadataUrl: string, message: string): Response;
+/** Fetches RFC 8414 metadata from the authorization server, falling back to built-in known values. */
+export declare function loadAuthServerMetadata(authServer: string, fetchImpl?: typeof fetch): Promise<OAuthMetadata>;

package/dist/auth.js

@@ -0,0 +1,94 @@
+/**
+ * Authentication in HTTP mode: this service is only an OAuth Resource Server.
+ *
+ * - The authorization server is account.jinshuju.net (dynamic registration / PKCE / refresh supported); this service
+ *   issues no tokens;
+ * - the request's Bearer (an OAuth token or a personal / account access token) goes to API v1 as is;
+ * - the API decides whether a token is valid: one light call (GET /me) checks it, and the result is cached by token
+ *   hash for a while, so every tool call does not spend an extra API request;
+ * - with no token or an invalid one, answers 401 + WWW-Authenticate: Bearer resource_metadata=..., and the client
+ *   goes through OAuth from there.
+ */
+import { bearerAuthChallengeResponse, OAuthError, OAuthErrorCode } from '@modelcontextprotocol/server';
+/** Token hash: the key of the verification cache, and the source of the analytics session id. */
+export async function sha256(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export class TokenVerifier {
+    options;
+    cache = new Map();
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    /** Returns AuthInfo when valid, undefined when not. A network failure counts as invalid but is not cached. */
+    async verify(token) {
+        const key = await sha256(token);
+        const hit = this.cache.get(key);
+        if (hit && hit.until > this.now())
+            return hit.info;
+        this.cache.delete(key);
+        const res = await this.options.api.raw('GET', '/me', token);
+        // 401 = the token itself is refused; any other status (200 / 402 / 403 for insufficient scope …) means the token is valid and only what it may do differs.
+        if (res.status === 401)
+            return undefined;
+        const me = (res.status === 200 ? res.json : undefined);
+        const info = {
+            token,
+            clientId: 'jinshuju',
+            scopes: [],
+            extra: me ? { userId: me.id, userName: me.name } : undefined
+        };
+        if (this.cache.size >= (this.options.maxEntries ?? 2000)) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(key, { info, until: this.now() + this.options.cacheTtlMs });
+        return info;
+    }
+    async forget(token) {
+        this.cache.delete(await sha256(token));
+    }
+}
+/** The Jinshuju user id in AuthInfo (the id from GET /me), undefined when no user was identified; analytics and Sentry both identify the user by it. */
+export function userIdOf(authInfo) {
+    const id = authInfo?.extra?.userId;
+    return id === undefined || id === null || id === '' ? undefined : String(id);
+}
+export function bearerToken(request) {
+    const header = request.headers.get('authorization');
+    const match = header && /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match ? match[1].trim() : undefined;
+}
+export function challenge(resourceMetadataUrl, message) {
+    return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.InvalidToken, message), { resourceMetadataUrl });
+}
+/** Fetches RFC 8414 metadata from the authorization server, falling back to built-in known values. */
+export async function loadAuthServerMetadata(authServer, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(`${authServer}/.well-known/oauth-authorization-server`, {
+            headers: { Accept: 'application/json' }
+        });
+        if (res.ok)
+            return (await res.json());
+    }
+    catch {
+        // fall through to the built-in values below
+    }
+    return {
+        issuer: authServer,
+        authorization_endpoint: `${authServer}/oauth/authorize`,
+        token_endpoint: `${authServer}/oauth/token`,
+        revocation_endpoint: `${authServer}/oauth/revoke`,
+        registration_endpoint: `${authServer}/oauth/register`,
+        scopes_supported: ['public', 'profile', 'forms', 'read_entries', 'write_entries', 'form_setting', 'users'],
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],
+        code_challenge_methods_supported: ['S256']
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/cli-credential.d.ts

@@ -0,0 +1,21 @@
+import { type Credential } from './credential.js';
+export declare const DEFAULT_CONFIG_PATH: string;
+export declare class CliSessionCredential implements Credential {
+    private readonly path;
+    private readonly authHost;
+    private readonly fetchImpl;
+    private config?;
+    private refreshing?;
+    constructor(path?: string, authHost?: string, fetchImpl?: typeof fetch);
+    static exists(path?: string): Promise<boolean>;
+    private load;
+    private session;
+    describe(): string;
+    token(): Promise<string>;
+    invalidate(): Promise<boolean>;
+    private refresh;
+    private doRefresh;
+    private save;
+}
+/** For the stdio entry: picks a credential source by priority. */
+export declare function resolveCredential(env?: Record<string, string | undefined>): Promise<Credential>;

package/dist/cli-credential.js

@@ -0,0 +1,120 @@
+/**
+ * The local credential for stdio mode, found the way @jinshuju/cli does. The JINSHUJU_ACCESS_TOKEN environment variable
+ * comes first, then the credential `jinshuju auth login` saved in ~/.jinshuju/config.json (an access token or an OAuth
+ * session; an expired session is renewed with refresh_token and written back, mode 600). Both tools share one login.
+ */
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { MissingCredentialError, StaticCredential } from './credential.js';
+export const DEFAULT_CONFIG_PATH = join(homedir(), '.jinshuju', 'config.json');
+const DEFAULT_CLIENT_ID = 'jinshuju_cli_public';
+export class CliSessionCredential {
+    path;
+    authHost;
+    fetchImpl;
+    config;
+    refreshing;
+    constructor(path = DEFAULT_CONFIG_PATH, authHost = 'https://account.jinshuju.net', fetchImpl = fetch) {
+        this.path = path;
+        this.authHost = authHost;
+        this.fetchImpl = fetchImpl;
+    }
+    static async exists(path = DEFAULT_CONFIG_PATH) {
+        try {
+            await readFile(path, 'utf8');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async load() {
+        if (!this.config)
+            this.config = JSON.parse(await readFile(this.path, 'utf8'));
+        return this.config;
+    }
+    session(config) {
+        const auth = config.auth;
+        return auth && auth.type === 'oauth' ? auth : undefined;
+    }
+    describe() {
+        const session = this.config && this.session(this.config);
+        return session ? `OAuth session (${this.path})` : `access token (${this.path})`;
+    }
+    async token() {
+        const config = await this.load();
+        const session = this.session(config);
+        if (session) {
+            const expiresAt = session.expires_at ? Date.parse(session.expires_at) : Number.NaN;
+            // Renew a minute early so the token does not expire mid-request
+            if (Number.isFinite(expiresAt) && expiresAt - Date.now() < 60_000 && session.refresh_token) {
+                await this.refresh();
+            }
+            return this.session(this.config).access_token;
+        }
+        const token = config.auth?.access_token ?? config.access_token;
+        if (!token)
+            throw new MissingCredentialError();
+        return token;
+    }
+    async invalidate() {
+        const config = await this.load();
+        if (!this.session(config)?.refresh_token)
+            return false;
+        return this.refresh();
+    }
+    refresh() {
+        // Concurrent tool calls share one renewal
+        this.refreshing ??= this.doRefresh().finally(() => {
+            this.refreshing = undefined;
+        });
+        return this.refreshing;
+    }
+    async doRefresh() {
+        const config = await this.load();
+        const session = this.session(config);
+        if (!session?.refresh_token)
+            return false;
+        const host = session.auth_host ?? config.auth_host ?? this.authHost;
+        const clientId = session.client_id ?? config.client_id ?? DEFAULT_CLIENT_ID;
+        const res = await this.fetchImpl(new URL('/oauth/token', host), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: new URLSearchParams({
+                grant_type: 'refresh_token',
+                refresh_token: session.refresh_token,
+                client_id: clientId
+            })
+        });
+        if (!res.ok)
+            return false;
+        const body = (await res.json());
+        const next = {
+            ...session,
+            access_token: body.access_token,
+            refresh_token: body.refresh_token ?? session.refresh_token,
+            expires_at: body.expires_in ? new Date(Date.now() + body.expires_in * 1000).toISOString() : session.expires_at,
+            scope: body.scope ?? session.scope
+        };
+        this.config = { ...config, auth: next };
+        await this.save(this.config);
+        return true;
+    }
+    async save(config) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+        await rename(tmp, this.path);
+    }
+}
+/** For the stdio entry: picks a credential source by priority. */
+export async function resolveCredential(env = process.env) {
+    if (env.JINSHUJU_ACCESS_TOKEN)
+        return new StaticCredential(env.JINSHUJU_ACCESS_TOKEN, 'env JINSHUJU_ACCESS_TOKEN');
+    const path = env.JINSHUJU_CONFIG ?? DEFAULT_CONFIG_PATH;
+    if (await CliSessionCredential.exists(path))
+        return new CliSessionCredential(path, env.JINSHUJU_AUTH_HOST);
+    throw new MissingCredentialError();
+}
+//# sourceMappingURL=cli-credential.js.map

package/dist/composites.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Composite tools: one call sends two requests: creating and editing exam / evaluation forms, and counting across forms.
+ * The generator assembles their input schema from openapi; this file only orchestrates: which request goes first, and what
+ * to say when one fails.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { type ToolRuntime } from './tools.js';
+import type { OperationSpec, ToolSpec } from './types.js';
+export declare const OPERATIONS: Record<string, OperationSpec>;
+type Args = Record<string, unknown>;
+export declare function runComposite(tool: ToolSpec, args: Args, runtime: ToolRuntime): Promise<CallToolResult>;
+export {};

package/dist/composites.js

@@ -0,0 +1,82 @@
+import { toToolResult } from './tools.js';
+import operationsJson from './generated/operations.json' with { type: 'json' };
+export const OPERATIONS = operationsJson;
+function op(id) {
+    const spec = OPERATIONS[id];
+    if (!spec)
+        throw new Error(`${id} is not in operations.json`);
+    return spec;
+}
+function ok(res) {
+    return res.status >= 200 && res.status < 300;
+}
+/**
+ * Arguments of the scene setting operation: an operation with a flattened body takes the setting keys at the top level;
+ * one whose body is a single schema (such as updateEvaluationSetting's EvaluationSettingInput pointer) takes them under
+ * the body.param key. Both follow the operation table; nothing is guessed here.
+ */
+function settingArgs(settingOp, formToken, setting) {
+    if (!settingOp.body || settingOp.body.flatten)
+        return { form_token: formToken, ...setting };
+    return { form_token: formToken, [settingOp.body.param ?? 'body']: setting };
+}
+function withText(result, text) {
+    const first = result.content[0];
+    if (first?.type === 'text')
+        first.text = `${text}\n${first.text}`;
+    return result;
+}
+export async function runComposite(tool, args, runtime) {
+    const { api, credential, maxResultChars } = runtime;
+    const composite = tool.composite;
+    if (composite.kind === 'count_entries') {
+        const tokens = args.form_token;
+        if (Array.isArray(tokens)) {
+            const { form_token: _ignored, ...rest } = args;
+            const res = await api.call(op('countEntriesAcrossForms'), { ...rest, form_tokens: tokens.join(',') }, credential);
+            return toToolResult(tool, res, maxResultChars);
+        }
+        return toToolResult(tool, await api.call(op('countEntries'), args, credential), maxResultChars);
+    }
+    const settingKey = composite.settingKey;
+    const settingOp = op(composite.settingOperation);
+    const settingsUpdated = `${composite.scene === 'exam' ? 'Exam' : 'Evaluation'} settings updated.`;
+    const { [settingKey]: setting, ...formArgs } = args;
+    const hasSetting = !!setting && typeof setting === 'object' && Object.keys(setting).length > 0;
+    if (composite.kind === 'scene_form_create') {
+        // Create the form first (to get its token), then write the scene settings; if the settings are rejected the form already exists, and the result must say so, or the caller creates another one.
+        const created = await api.call(op('createForm'), { ...formArgs, scene: composite.scene }, credential);
+        if (!ok(created))
+            return toToolResult(tool, created, maxResultChars);
+        const token = created.json?.token;
+        if (!hasSetting || !token)
+            return toToolResult(tool, created, maxResultChars);
+        const updated = await api.call(settingOp, settingArgs(settingOp, token, setting), credential);
+        if (!ok(updated)) {
+            const failure = toToolResult(tool, updated, maxResultChars);
+            return withText(failure, `The form was created (token=${token}), but its ${composite.scene} settings were rejected; retry ${settingKey} alone with edit_${composite.scene}_form.`);
+        }
+        return withText(toToolResult(tool, created, maxResultChars), `${settingsUpdated} Form:`);
+    }
+    // scene_form_update: the settings go first (they are the half that may be rejected: a form not in that scene); if they are rejected, none of the other changes are sent.
+    const formToken = formArgs.form_token;
+    const hasFormChanges = Object.keys(formArgs).some((k) => k !== 'form_token' && formArgs[k] !== undefined);
+    let settingResult;
+    if (hasSetting) {
+        settingResult = await api.call(settingOp, settingArgs(settingOp, formToken, setting), credential);
+        if (!ok(settingResult))
+            return toToolResult(tool, settingResult, maxResultChars);
+    }
+    if (!hasFormChanges) {
+        return settingResult
+            ? withText(toToolResult(tool, settingResult, maxResultChars), settingsUpdated)
+            : { isError: true, content: [{ type: 'text', text: `Nothing to change: pass ${settingKey} or form fields.` }] };
+    }
+    const updated = await api.call(op('updateForm'), formArgs, credential);
+    const result = toToolResult(tool, updated, maxResultChars);
+    if (settingResult) {
+        return withText(result, ok(updated) ? `${settingsUpdated} Form:` : `${settingsUpdated} The form changes were rejected:`);
+    }
+    return result;
+}
+//# sourceMappingURL=composites.js.map

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Runtime configuration. The HTTP deployment reads it from environment variables (Node) or the Workers env; stdio uses only the API-related part.
+ */
+export interface Config {
+    /** API v1 base URL, https://jinshuju.net/api/v1 by default */
+    apiBaseUrl: string;
+    /** OAuth authorization server (issuer), https://account.jinshuju.net by default */
+    authServer: string;
+    /**
+     * Public addresses of this service, possibly several (e.g. the custom domain https://mcp.jinshuju.net and the platform's
+     * default prefixed address https://host/jinshuju-mcp). One is picked by the request's Host, falling back to the first;
+     * when empty, each request's X-Forwarded-* / Host decides.
+     */
+    publicUrls: string[];
+    /** Most characters one tool result returns; beyond it the result is truncated with a hint to narrow it */
+    maxResultChars: number;
+    /** How long token verification results are cached in HTTP mode (ms) */
+    tokenCacheTtlMs: number;
+    /** Timeout of API calls (ms) */
+    timeoutMs: number;
+    /** PostHog project token (phc_…) for MCP analytics in HTTP mode; nothing is reported when empty */
+    posthogApiKey?: string;
+    /** PostHog ingest host, https://us.i.posthog.com by default */
+    posthogHost: string;
+    /** Whether to collect the call intent the model writes (each tool's context argument → $mcp_intent); on by default */
+    collectIntent: boolean;
+}
+export declare const DEFAULTS: Config;
+type EnvLike = Record<string, string | undefined>;
+/** JINSHUJU_MCP_PUBLIC_URL: several comma-separated addresses, with trailing slashes and empty items removed. */
+export declare function publicUrlsFromEnv(value: string | undefined): string[];
+/** Reads the configuration from environment variables; keys carry the JINSHUJU_ prefix, as in @jinshuju/cli. */
+export declare function configFromEnv(env?: EnvLike): Config;
+export {};