qyl-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 ancplua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# qyl-mcp-server
+
+qyl telemetry MCP server: trace explorer, MCP dashboard, log search, and CI-run
+inspection for a live [qyl](https://github.com/ANcpLua/qyl) collector — or an
+explicit, visibly labelled demo mode.
+
+```bash
+npx qyl-mcp-server --stdio    # stdio MCP server
+npx qyl-mcp-server            # Streamable HTTP on loopback
+```
+
+Works standalone with any MCP client, and composes with the qyl local stack —
+`qyl up --mcp-stdio npx qyl-mcp-server --stdio` supervises it next to the
+collector with reads and OTLP export pre-wired.
+
+## Tools
+
+`fetch_telemetry`, `list_traces`, `get_trace`, `list_sessions`, `search_logs`,
+`display_traces`, `display_mcp_dashboard`, `ci_log` — all published with
+read-only safety annotations. The two `display_*` tools return MCP Apps UI
+resources (single-file viewers).
+
+Every inbound `tools/call` is recorded natively: validated result, lifecycle,
+duration, redacted JSON-RPC timeline, and trace/span correlation are persisted
+atomically to `~/.qyl/mcp-native-executions.json`.
+
+## Configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `QYL_COLLECTOR_URL` | qyl read API base; default `http://127.0.0.1:5100`. Also the OTLP base when set. |
+| `QYL_API_KEY` | Collector read and OTLP credential. |
+| `QYL_OTLP_ENDPOINT` | Optional OTLP base for self-telemetry. |
+| `QYL_DEMO=1` | Explicit generated demo telemetry. Collector failure never silently substitutes demo data. |
+| `QYL_MCP_TELEMETRY=0` | Disable MCP spans and duration metrics. |
+| `QYL_MCP_NATIVE_STATE_PATH` | Override the native execution-evidence path. |
+
+Secrets are redacted before results reach the model, structured content, or
+durable evidence.
+
+Full documentation: [github.com/ANcpLua/qyl.mcp](https://github.com/ANcpLua/qyl.mcp)

package/dist/atomic-json-store.d.ts

@@ -0,0 +1,37 @@
+export type PersistenceErrorKind = "invalid_json" | "invalid_state" | "write_failed";
+export declare class PersistenceError extends Error {
+    readonly kind: PersistenceErrorKind;
+    constructor(kind: PersistenceErrorKind, message: string, options?: ErrorOptions);
+}
+export interface AtomicJsonStoreOptions<T> {
+    initial: () => T;
+    /** Validates untrusted data loaded from disk and returns its normalized representation. */
+    parse: (value: unknown) => T;
+    /** Redacts or rejects sensitive state before it can reach disk. */
+    prepareForWrite: (value: T) => T;
+}
+/**
+ * A single-process, serialized JSON store with restrictive permissions and atomic replacement.
+ * Domain services remain responsible for workspace scoping; this class guarantees that a failed
+ * validation or write never replaces the last known-good document.
+ */
+export declare class AtomicJsonStore<T> {
+    private readonly filePath;
+    private readonly options;
+    private state;
+    private initialization;
+    private tail;
+    constructor(filePath: string, options: AtomicJsonStoreOptions<T>);
+    initialize(): Promise<void>;
+    read(): Promise<T>;
+    replace(value: T): Promise<T>;
+    transact<R>(mutate: (draft: T) => R | Promise<R>): Promise<{
+        state: T;
+        result: R;
+    }>;
+    private load;
+    private commit;
+    private writePrepared;
+    private enqueue;
+    private requireState;
+}

package/dist/atomic-json-store.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+export class PersistenceError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.name = "PersistenceError";
+    }
+}
+/**
+ * A single-process, serialized JSON store with restrictive permissions and atomic replacement.
+ * Domain services remain responsible for workspace scoping; this class guarantees that a failed
+ * validation or write never replaces the last known-good document.
+ */
+export class AtomicJsonStore {
+    filePath;
+    options;
+    state;
+    initialization;
+    tail = Promise.resolve();
+    constructor(filePath, options) {
+        this.filePath = filePath;
+        this.options = options;
+    }
+    async initialize() {
+        this.initialization ??= this.load();
+        return this.initialization;
+    }
+    async read() {
+        await this.initialize();
+        // Reads participate in the same happens-before order as writes. This is
+        // required for deletion guards and idempotency lookups: returning the
+        // cached document while an earlier transaction is still pending can
+        // expose stale ownership or active-work state.
+        await this.tail;
+        return clone(this.requireState());
+    }
+    async replace(value) {
+        return this.enqueue(async () => this.commit(value));
+    }
+    async transact(mutate) {
+        return this.enqueue(async () => {
+            const draft = clone(this.requireState());
+            const result = await mutate(draft);
+            const state = await this.commit(draft);
+            return { state, result };
+        });
+    }
+    async load() {
+        let text;
+        try {
+            text = await readFile(this.filePath, "utf8");
+        }
+        catch (error) {
+            if (isNodeError(error, "ENOENT")) {
+                this.state = await this.writePrepared(this.options.initial());
+                return;
+            }
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw new PersistenceError("invalid_json", `Persisted qyl.mcp state at '${this.filePath}' is not valid JSON.`, { cause: error });
+        }
+        try {
+            this.state = clone(this.options.parse(parsed));
+        }
+        catch (error) {
+            throw new PersistenceError("invalid_state", `Persisted qyl.mcp state at '${this.filePath}' does not satisfy the current schema.`, { cause: error });
+        }
+    }
+    async commit(value) {
+        await this.initialize();
+        const normalized = await this.writePrepared(value);
+        this.state = normalized;
+        return clone(normalized);
+    }
+    async writePrepared(value) {
+        let normalized;
+        try {
+            const prepared = this.options.prepareForWrite(clone(value));
+            normalized = this.options.parse(prepared);
+        }
+        catch (error) {
+            throw new PersistenceError("invalid_state", "qyl.mcp refused to persist state that is invalid or contains unsupported sensitive data.", { cause: error });
+        }
+        const json = JSON.stringify(normalized, null, 2);
+        if (json === undefined) {
+            throw new PersistenceError("invalid_state", "qyl.mcp state cannot be represented as JSON.");
+        }
+        try {
+            await writeAtomically(this.filePath, `${json}\n`);
+        }
+        catch (error) {
+            throw new PersistenceError("write_failed", `qyl.mcp could not persist state at '${this.filePath}'.`, { cause: error });
+        }
+        return clone(normalized);
+    }
+    enqueue(operation) {
+        const queued = this.tail.then(operation, operation);
+        this.tail = queued.then(() => undefined, () => undefined);
+        return queued;
+    }
+    requireState() {
+        if (this.state === undefined) {
+            throw new Error("AtomicJsonStore must be initialized before accessing state.");
+        }
+        return this.state;
+    }
+}
+async function writeAtomically(filePath, contents) {
+    const directory = dirname(filePath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+    const handle = await open(temporaryPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    let renamed = false;
+    try {
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        await handle.close();
+        await rename(temporaryPath, filePath);
+        renamed = true;
+        await chmod(filePath, 0o600);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+        if (!renamed)
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function isNodeError(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+//# sourceMappingURL=atomic-json-store.js.map

package/dist/atomic-json-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-json-store.js","sourceRoot":"","sources":["../src/atomic-json-store.ts"],"names":[],"mappings":"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"}

package/dist/ci.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Qyl's CI dogfooding block (the fourth tool block next to traces, sessions,
+ * and logs): answers "which CI leg hung on what" from qyl's OWN telemetry
+ * instead of wrapping the GitHub API.
+ *
+ * Emitter convention (what CI runs must send to appear here):
+ *   - resource `service.name` starts with "qyl-ci" (e.g. "qyl-ci-smoke"),
+ *   - `session.id` identifies one workflow run (e.g. "nuget-publish-<run_id>"),
+ *   - one span per phase, named after the phase, carrying a `ci.leg` string
+ *     attribute (e.g. "macos-latest"); a failed phase sets span status error.
+ *
+ * The input/output schemas are deliberately inline zod, not
+ * publishedContractSchema: this is an operational view over already-published
+ * OTel contract data, not a new wire contract. If it graduates, it moves to
+ * qyl-api-schema first.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { Mode, QylSession, QylTrace } from "./wire.js";
+/** Resource service-name prefix that marks telemetry as CI-emitted. */
+export declare const CI_SERVICE_PREFIX = "qyl-ci";
+declare const CiRunSummarySchema: z.ZodObject<{
+    run_id: z.ZodString;
+    state: z.ZodString;
+    start_time: z.ZodString;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    error_count: z.ZodNumber;
+    services: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const CiPhaseSchema: z.ZodObject<{
+    leg: z.ZodString;
+    phase: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        unset: "unset";
+    }>;
+    duration_ms: z.ZodNumber;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CiRunSummary = z.infer<typeof CiRunSummarySchema>;
+type CiPhase = z.infer<typeof CiPhaseSchema>;
+/** CI sessions are the ones that carry at least one qyl-ci service. */
+export declare function filterCiSessions(sessions: QylSession[]): QylSession[];
+/** Flatten a run's traces into per-leg phases, failures first. */
+export declare function collectCiPhases(traces: QylTrace[]): CiPhase[];
+export declare function summarizeCiRuns(runs: CiRunSummary[], mode: Mode): string;
+export declare function summarizeCiRun(runId: string, phases: CiPhase[], mode: Mode): string;
+/** Register the CI dogfooding block. */
+export declare function registerCiTools(server: McpServer): void;
+export {};

package/dist/ci.js

@@ -0,0 +1,158 @@
+/**
+ * Qyl's CI dogfooding block (the fourth tool block next to traces, sessions,
+ * and logs): answers "which CI leg hung on what" from qyl's OWN telemetry
+ * instead of wrapping the GitHub API.
+ *
+ * Emitter convention (what CI runs must send to appear here):
+ *   - resource `service.name` starts with "qyl-ci" (e.g. "qyl-ci-smoke"),
+ *   - `session.id` identifies one workflow run (e.g. "nuget-publish-<run_id>"),
+ *   - one span per phase, named after the phase, carrying a `ci.leg` string
+ *     attribute (e.g. "macos-latest"); a failed phase sets span status error.
+ *
+ * The input/output schemas are deliberately inline zod, not
+ * publishedContractSchema: this is an operational view over already-published
+ * OTel contract data, not a new wire contract. If it graduates, it moves to
+ * qyl-api-schema first.
+ */
+import { z } from "zod";
+import { fetchSessions, fetchSessionTraces } from "./data.js";
+import { telemetryToolResult } from "./telemetry-redaction.js";
+import { READ_ONLY_TELEMETRY_TOOL_ANNOTATIONS, toolError } from "./tools.js";
+/** Resource service-name prefix that marks telemetry as CI-emitted. */
+export const CI_SERVICE_PREFIX = "qyl-ci";
+const CiLogInputSchema = z.object({
+    run_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Session id of one CI run for a per-leg phase breakdown; omit to list recent runs."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Maximum CI runs to list (default 10)."),
+});
+const CiRunSummarySchema = z.object({
+    run_id: z.string(),
+    state: z.string(),
+    start_time: z.string(),
+    duration_ms: z.number().optional(),
+    error_count: z.number(),
+    services: z.array(z.string()),
+});
+const CiPhaseSchema = z.object({
+    leg: z.string(),
+    phase: z.string(),
+    status: z.enum(["ok", "error", "unset"]),
+    duration_ms: z.number(),
+    message: z.string().optional(),
+});
+const CiLogOutputSchema = z.object({
+    runs: z.array(CiRunSummarySchema).optional(),
+    run_id: z.string().optional(),
+    phases: z.array(CiPhaseSchema).optional(),
+    mode: z.enum(["live", "demo"]),
+});
+/** CI sessions are the ones that carry at least one qyl-ci service. */
+export function filterCiSessions(sessions) {
+    return sessions.filter((session) => session.services.some((service) => service.startsWith(CI_SERVICE_PREFIX)));
+}
+function spanLeg(span) {
+    const attribute = span.attributes?.find((entry) => entry.key === "ci.leg");
+    return typeof attribute?.value === "string"
+        ? attribute.value
+        : span.resource["service.name"];
+}
+/** Flatten a run's traces into per-leg phases, failures first. */
+export function collectCiPhases(traces) {
+    const phases = traces.flatMap((trace) => trace.spans.map((span) => ({
+        leg: spanLeg(span),
+        phase: span.name,
+        status: span.status.code === 2 ? "error" : span.status.code === 1 ? "ok" : "unset",
+        duration_ms: Math.max(0, Math.round((span.end_time_unix_nano - span.start_time_unix_nano) / 1_000_000)),
+        ...(span.status.message ? { message: span.status.message } : {}),
+    })));
+    return phases.sort((a, b) => a.status === b.status
+        ? a.leg.localeCompare(b.leg) || a.phase.localeCompare(b.phase)
+        : a.status === "error"
+            ? -1
+            : b.status === "error"
+                ? 1
+                : 0);
+}
+export function summarizeCiRuns(runs, mode) {
+    if (runs.length === 0) {
+        return `No CI runs found (${mode} mode). CI telemetry appears once runs emit ` +
+            `spans with a '${CI_SERVICE_PREFIX}*' service.name.`;
+    }
+    const lines = runs.map((run) => {
+        const failure = run.error_count > 0 ? `${run.error_count} error(s)` : "clean";
+        const duration = run.duration_ms === undefined ? "?" : `${Math.round(run.duration_ms / 1000)}s`;
+        return `- ${run.run_id} [${run.state}] ${run.start_time} ${duration} — ${failure}`;
+    });
+    return `${runs.length} CI run(s) (${mode} mode), pass a run_id for the per-leg breakdown:\n${lines.join("\n")}`;
+}
+export function summarizeCiRun(runId, phases, mode) {
+    if (phases.length === 0) {
+        return `CI run ${runId} has no phase spans (${mode} mode).`;
+    }
+    const legs = new Map();
+    for (const phase of phases) {
+        const existing = legs.get(phase.leg);
+        if (existing)
+            existing.push(phase);
+        else
+            legs.set(phase.leg, [phase]);
+    }
+    const lines = [];
+    for (const [leg, legPhases] of legs) {
+        const failed = legPhases.filter((phase) => phase.status === "error");
+        lines.push(`${failed.length > 0 ? "✗" : "✓"} ${leg}`);
+        for (const phase of failed.length > 0 ? failed : legPhases) {
+            const detail = phase.message ? ` — ${phase.message}` : "";
+            lines.push(`    ${phase.status === "error" ? "✗" : "·"} ${phase.phase} (${phase.duration_ms}ms)${detail}`);
+        }
+    }
+    return `CI run ${runId} (${mode} mode):\n${lines.join("\n")}`;
+}
+/** Register the CI dogfooding block. */
+export function registerCiTools(server) {
+    server.registerTool("ci_log", {
+        title: "CI Log",
+        description: "Read qyl's own CI runs from its telemetry (dogfooding — no GitHub API). " +
+            "Without arguments: recent CI runs (sessions whose service.name starts with " +
+            `'${CI_SERVICE_PREFIX}'). With run_id: per-leg phase breakdown, failures first, ` +
+            "so 'which leg hung on what' is answerable even when GitHub's log API is down.",
+        inputSchema: CiLogInputSchema.shape,
+        outputSchema: CiLogOutputSchema.shape,
+        annotations: READ_ONLY_TELEMETRY_TOOL_ANNOTATIONS,
+    }, async (args) => {
+        try {
+            if (args.run_id) {
+                const { traces, mode } = await fetchSessionTraces(args.run_id, 100);
+                const phases = collectCiPhases(traces);
+                const output = { run_id: args.run_id, phases, mode };
+                return telemetryToolResult(summarizeCiRun(args.run_id, phases, mode), output);
+            }
+            const { sessions, mode } = await fetchSessions(50, undefined);
+            const runs = filterCiSessions(sessions)
+                .slice(0, args.limit ?? 10)
+                .map((session) => ({
+                run_id: session["session.id"],
+                state: session.state,
+                start_time: session.start_time,
+                ...(session.duration_ms === undefined ? {} : { duration_ms: session.duration_ms }),
+                error_count: session.error_count,
+                services: session.services,
+            }));
+            const output = { runs, mode };
+            return telemetryToolResult(summarizeCiRuns(runs, mode), output);
+        }
+        catch (err) {
+            return toolError(err);
+        }
+    });
+}
+//# sourceMappingURL=ci.js.map

package/dist/ci.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci.js","sourceRoot":"","sources":["../src/ci.ts"],"names":[],"mappings":"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"}

package/dist/collector.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Collector REST client + live/demo mode selection.
+ *
+ * QYL_DEMO=1 selects explicit demo mode. Every other invocation is live;
+ * connection, HTTP, JSON, and contract failures surface to the caller rather
+ * than silently substituting generated telemetry or invented defaults.
+ */
+import type { LogRecord, SessionEntity, Trace } from "@ancplua/qyl-api-schema/types";
+import { z } from "zod";
+import type { Mode } from "./wire.js";
+/** Error with a message already suitable for showing to the model/user. */
+export declare class CollectorError extends Error {
+    readonly connectionError: boolean;
+    readonly status?: number | undefined;
+    constructor(message: string, connectionError?: boolean, status?: number | undefined);
+}
+/** Normalize RFC 3339 spelling, then enforce the public Trace schema exactly. */
+export declare function parseCollectorTrace(value: unknown, context?: string): Trace;
+/** Normalize RFC 3339 spelling, then enforce the public Session schema exactly. */
+export declare function parseCollectorSession(value: unknown, context?: string): SessionEntity;
+/** Enforce the public LogRecord schema without alternate wire encodings. */
+export declare function parseCollectorLog(value: unknown, context?: string): LogRecord;
+interface ParsedCollectorPage<T> {
+    items: T[];
+    hasMore: boolean;
+}
+/**
+ * Normalize endpoint items, then validate the complete operation-specific
+ * response body. The supplied schema must be an Operations.*.Response.200
+ * definition from the generated contract.
+ */
+export declare function parseCollectorPage<T, TPage extends {
+    items: T[];
+    has_more: boolean;
+}>(value: unknown, context: string, pageSchema: z.ZodType<TPage>, parseItem: (item: unknown, context: string) => T): ParsedCollectorPage<T>;
+/**
+ * GET a collector endpoint. Query params are camelCase per the collector API;
+ * `undefined` values are omitted. All response data remains unknown until the
+ * endpoint-specific generated contract parser accepts it.
+ */
+export declare function collectorGet(pathname: string, params?: Record<string, string | number | boolean | undefined>): Promise<unknown>;
+export declare function resolveMode(): Promise<Mode>;
+export {};