oops-errors-mcp 0.0.0-stage → 0.1.0

package/dist/issue.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Issue references as agents and humans write them.
+ *
+ * The REST API accepts either the issue uuid or its per-project number in the
+ * `<issue_id>` path segment, so the server only has to normalise what the
+ * model passed: `12`, `"12"`, `"#12"` and `" # 12 "` all become `"12"`; a uuid
+ * passes through unchanged (lower-cased); anything else is rejected before a
+ * request is made.
+ */
+export declare class InvalidIssueRef extends Error {
+    readonly input: unknown;
+    constructor(input: unknown);
+}
+/** Returns the path segment to use with the API (`"12"` or the uuid). */
+export declare function parseIssueRef(input: string | number): string;
+/** `#12` for numbers, the uuid otherwise: how the reference is echoed back in summaries. */
+export declare function formatIssueRef(ref: string): string;

package/dist/issue.js

@@ -0,0 +1,42 @@
+/**
+ * Issue references as agents and humans write them.
+ *
+ * The REST API accepts either the issue uuid or its per-project number in the
+ * `<issue_id>` path segment, so the server only has to normalise what the
+ * model passed: `12`, `"12"`, `"#12"` and `" # 12 "` all become `"12"`; a uuid
+ * passes through unchanged (lower-cased); anything else is rejected before a
+ * request is made.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMBER_RE = /^#?\s*(\d{1,9})$/;
+export class InvalidIssueRef extends Error {
+    input;
+    constructor(input) {
+        super(`Invalid issue reference ${JSON.stringify(input)}: pass the issue uuid, its number (12) or "#12".`);
+        this.input = input;
+        this.name = "InvalidIssueRef";
+    }
+}
+/** Returns the path segment to use with the API (`"12"` or the uuid). */
+export function parseIssueRef(input) {
+    if (typeof input === "number") {
+        if (!Number.isInteger(input) || input < 1)
+            throw new InvalidIssueRef(input);
+        return String(input);
+    }
+    const s = input.trim();
+    if (UUID_RE.test(s))
+        return s.toLowerCase();
+    const m = NUMBER_RE.exec(s);
+    if (m) {
+        const n = Number(m[1]);
+        if (n >= 1)
+            return String(n);
+    }
+    throw new InvalidIssueRef(input);
+}
+/** `#12` for numbers, the uuid otherwise: how the reference is echoed back in summaries. */
+export function formatIssueRef(ref) {
+    return /^\d+$/.test(ref) ? `#${ref}` : ref;
+}
+//# sourceMappingURL=issue.js.map

package/dist/issue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../src/issue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAClF,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACZ;IAA5B,YAA4B,KAAc;QACxC,KAAK,CAAC,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QADhF,UAAK,GAAL,KAAK,CAAS;QAExC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,KAAsB;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC;QACN,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AAC7C,CAAC"}

package/dist/rbac.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Tool-level authorization.
+ *
+ * Every tool declares the scope(s) it needs. The server consults this table
+ * twice (defense in depth):
+ *
+ *   1. at registration — tools the key cannot use are never listed, so the
+ *      model is not tempted to call them;
+ *   2. at call time — a tool that is somehow invoked without its scope is
+ *      refused and the refusal is audited.
+ *
+ * The REST API enforces the same scopes independently (layer 3), so a bug in
+ * this file can never *grant* access, only hide it.
+ *
+ * The table mirrors the "MCP server" section of CONTRACT.md; the roles that
+ * grant each scope live in packages/shared/api_key_roles.json.
+ */
+import type { Scope } from "./types.js";
+export declare const TOOL_SCOPES: {
+    readonly list_projects: readonly ["projects:read"];
+    readonly get_project: readonly ["projects:read"];
+    readonly create_project: readonly ["projects:write"];
+    readonly update_project: readonly ["projects:write"];
+    readonly rotate_public_key: readonly ["projects:write"];
+    readonly delete_project: readonly ["projects:delete"];
+    readonly list_issues: readonly ["issues:read"];
+    readonly get_issue: readonly ["issues:read"];
+    readonly list_issue_events: readonly ["issues:read"];
+    readonly get_event: readonly ["issues:read"];
+    readonly search_events: readonly ["issues:read"];
+    readonly update_issue: readonly ["issues:write"];
+    readonly bulk_update_issues: readonly ["issues:write"];
+    readonly get_stats: readonly ["issues:read"];
+    readonly get_live: readonly ["issues:read"];
+    readonly purge_events: readonly ["events:delete"];
+    readonly get_usage: readonly ["usage:read"];
+    readonly get_audit_log: readonly ["audit:read"];
+    readonly report_error: readonly ["projects:read"];
+};
+export type ToolName = keyof typeof TOOL_SCOPES;
+export declare const ALL_TOOLS: ToolName[];
+/** Tools that never run without explicit user confirmation. */
+export declare const CONFIRMED_TOOLS: readonly ToolName[];
+export declare function hasScope(scopes: Iterable<Scope>, scope: Scope): boolean;
+/** True when every scope the tool needs is granted. */
+export declare function hasAllScopes(scopes: Iterable<Scope>, required: readonly Scope[]): boolean;
+export declare function allowedTools(scopes: Iterable<Scope>): ToolName[];

package/dist/rbac.js

@@ -0,0 +1,45 @@
+export const TOOL_SCOPES = {
+    // projects
+    list_projects: ["projects:read"],
+    get_project: ["projects:read"],
+    create_project: ["projects:write"],
+    update_project: ["projects:write"],
+    rotate_public_key: ["projects:write"],
+    delete_project: ["projects:delete"],
+    // issues and events
+    list_issues: ["issues:read"],
+    get_issue: ["issues:read"],
+    list_issue_events: ["issues:read"],
+    get_event: ["issues:read"],
+    search_events: ["issues:read"],
+    update_issue: ["issues:write"],
+    bulk_update_issues: ["issues:write"],
+    // stats
+    get_stats: ["issues:read"],
+    get_live: ["issues:read"],
+    purge_events: ["events:delete"],
+    // account
+    get_usage: ["usage:read"],
+    get_audit_log: ["audit:read"],
+    // reporting: needs to read the project's public key, then posts to /ingest
+    report_error: ["projects:read"],
+};
+export const ALL_TOOLS = Object.keys(TOOL_SCOPES);
+/** Tools that never run without explicit user confirmation. */
+export const CONFIRMED_TOOLS = ["delete_project", "purge_events"];
+export function hasScope(scopes, scope) {
+    for (const s of scopes)
+        if (s === scope)
+            return true;
+    return false;
+}
+/** True when every scope the tool needs is granted. */
+export function hasAllScopes(scopes, required) {
+    const set = new Set(scopes);
+    return required.every((s) => set.has(s));
+}
+export function allowedTools(scopes) {
+    const set = new Set(scopes);
+    return ALL_TOOLS.filter((tool) => TOOL_SCOPES[tool].every((s) => set.has(s)));
+}
+//# sourceMappingURL=rbac.js.map

package/dist/rbac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.js","sourceRoot":"","sources":["../src/rbac.ts"],"names":[],"mappings":"AAmBA,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,aAAa,EAAE,CAAC,eAAe,CAAC;IAChC,WAAW,EAAE,CAAC,eAAe,CAAC;IAC9B,cAAc,EAAE,CAAC,gBAAgB,CAAC;IAClC,cAAc,EAAE,CAAC,gBAAgB,CAAC;IAClC,iBAAiB,EAAE,CAAC,gBAAgB,CAAC;IACrC,cAAc,EAAE,CAAC,iBAAiB,CAAC;IACnC,oBAAoB;IACpB,WAAW,EAAE,CAAC,aAAa,CAAC;IAC5B,SAAS,EAAE,CAAC,aAAa,CAAC;IAC1B,iBAAiB,EAAE,CAAC,aAAa,CAAC;IAClC,SAAS,EAAE,CAAC,aAAa,CAAC;IAC1B,aAAa,EAAE,CAAC,aAAa,CAAC;IAC9B,YAAY,EAAE,CAAC,cAAc,CAAC;IAC9B,kBAAkB,EAAE,CAAC,cAAc,CAAC;IACpC,QAAQ;IACR,SAAS,EAAE,CAAC,aAAa,CAAC;IAC1B,QAAQ,EAAE,CAAC,aAAa,CAAC;IACzB,YAAY,EAAE,CAAC,eAAe,CAAC;IAC/B,UAAU;IACV,SAAS,EAAE,CAAC,YAAY,CAAC;IACzB,aAAa,EAAE,CAAC,YAAY,CAAC;IAC7B,2EAA2E;IAC3E,YAAY,EAAE,CAAC,eAAe,CAAC;CACoB,CAAC;AAItD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAe,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAwB,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC;AAEvF,MAAM,UAAU,QAAQ,CAAC,MAAuB,EAAE,KAAY;IAC5D,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,IAAI,CAAC,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC;IACrD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,QAA0B;IAC9E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The oops MCP server: tools, resources and prompts over the oops management
+ * API (plus the ingest endpoint for `report_error`).
+ *
+ * Design notes (the parts worth reading before changing anything):
+ *
+ * - **RBAC, three layers.** The key's scopes (from `GET /apikeys/me`) decide
+ *   which tools are *registered* (hidden tools are never listed), each handler
+ *   re-checks its scopes at call time, and the REST API enforces the same
+ *   scopes independently. See `rbac.ts`.
+ * - **Human approval for destructive actions.** `delete_project` and
+ *   `purge_events` ask the user through MCP *elicitation* when the client
+ *   supports it (Claude Code, the Inspector). Otherwise they refuse until the
+ *   model passes `confirm: true`, which forces the model to ask the user first.
+ * - **Structured outputs.** Every tool declares an `outputSchema` and returns
+ *   `structuredContent`, so hosts can validate and chain results without
+ *   parsing prose. Objects that mirror API responses are *loose* (extra fields
+ *   allowed) so an additive API change never breaks client-side validation.
+ *   The text content is a compact, human/agent-readable summary.
+ * - **Errors are results, not exceptions.** API errors come back as
+ *   `isError: true` with the stable error code, so the model can recover
+ *   (e.g. `limit_reached` → tell the user to upgrade) instead of crashing.
+ * - **Everything is audited**, locally (`audit.ts`) and server-side.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AuditSink } from "./audit.js";
+import { type OopsClient } from "./client.js";
+import type { KeyInfo } from "./types.js";
+export interface OopsServerOptions {
+    client: OopsClient;
+    keyInfo: KeyInfo;
+    audit: AuditSink;
+    /** Label written to the audit log: "stdio" | "http". */
+    transport?: string;
+    /**
+     * Whether destructive tools may ask the user via elicitation. Only safe on
+     * a transport with a persistent back-channel (stdio). Default: true.
+     */
+    allowElicitation?: boolean;
+}
+export declare function buildInstructions(info: KeyInfo): string;
+export declare function createOopsServer(opts: OopsServerOptions): McpServer;