queue-inspector-mcp 0.1.0

package/dist/format.js

@@ -0,0 +1,49 @@
+const utf8Fatal = new TextDecoder("utf-8", { fatal: true });
+/** True when the buffer decodes as UTF-8 and holds no C0 control bytes other
+ *  than tab, newline and carriage return. Anything else is treated as binary. */
+function looksLikeText(buf) {
+    try {
+        utf8Fatal.decode(buf);
+    }
+    catch {
+        return false;
+    }
+    for (const byte of buf) {
+        if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d)
+            return false;
+    }
+    return true;
+}
+/**
+ * Renders a raw payload for display. Text is returned as UTF-8; binary or
+ * otherwise non-text bytes are returned base64-encoded. Either way the result
+ * is capped at `maxBytes` of source data so a large payload cannot flood a tool
+ * response.
+ */
+export function decodePayload(buf, maxBytes = 8 * 1024) {
+    const truncated = buf.length > maxBytes;
+    const slice = truncated ? buf.subarray(0, maxBytes) : buf;
+    const isText = looksLikeText(slice);
+    return {
+        payload: isText ? slice.toString("utf8") : slice.toString("base64"),
+        payloadEncoding: isText ? "utf8" : "base64",
+        payloadBytes: buf.length,
+        payloadTruncated: truncated,
+    };
+}
+export function truncate(text, max = 240) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}… (${text.length} chars)`;
+}
+export function isoFromUnixSeconds(seconds) {
+    if (!seconds || seconds <= 0)
+        return null;
+    return new Date(seconds * 1000).toISOString();
+}
+export function isoFromMillis(ms) {
+    if (!ms || ms <= 0)
+        return null;
+    return new Date(ms).toISOString();
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAS5D;iFACiF;AACjF,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,CAAC;QACH,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,QAAQ,GAAG,CAAC,GAAG,IAAI;IAC5D,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC;IACxC,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1D,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACnE,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;QAC3C,YAAY,EAAE,GAAG,CAAC,MAAM;QACxB,gBAAgB,EAAE,SAAS;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,GAAG,GAAG,GAAG;IAC9C,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,SAAS,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,IAAI,CAAC,OAAO,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAA6B;IACzD,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createRedis } from "./redis.js";
+import { BackendRegistry } from "./backends/index.js";
+import { createServer } from "./server.js";
+async function main() {
+    const config = loadConfig();
+    const redis = createRedis(config.redisUrl);
+    const registry = new BackendRegistry(redis, config);
+    const server = createServer({ registry, readOnly: config.readOnly });
+    const shutdown = async () => {
+        try {
+            await server.close();
+        }
+        finally {
+            redis.disconnect();
+        }
+    };
+    process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
+    process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs; stdout carries the MCP protocol.
+    const mode = config.readOnly ? " (read-only)" : "";
+    process.stderr.write(`queue-inspector-mcp: connected, backends=[${config.backends.join(", ")}]${mode}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`queue-inspector-mcp: fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAErE,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,CAAC;IACH,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,4DAA4D;IAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,6CAA6C,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CACpF,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/redis.d.ts

@@ -0,0 +1,13 @@
+import { Redis } from "ioredis";
+/**
+ * Creates an ioredis client. `lazyConnect` keeps startup cheap: the connection
+ * opens on first command, so the process can register tools before Redis is
+ * reachable. `SCAN`-based discovery below never uses `KEYS`, so a large
+ * production database is walked in bounded batches.
+ */
+export declare function createRedis(url: string): Redis;
+/**
+ * Iterates keys matching a pattern with `SCAN`, collecting the results. Uses a
+ * generous `COUNT` hint but never blocks Redis the way `KEYS` would.
+ */
+export declare function scanKeys(redis: Redis, match: string, count?: number): Promise<string[]>;

package/dist/redis.js

@@ -0,0 +1,30 @@
+import { Redis } from "ioredis";
+/**
+ * Creates an ioredis client. `lazyConnect` keeps startup cheap: the connection
+ * opens on first command, so the process can register tools before Redis is
+ * reachable. `SCAN`-based discovery below never uses `KEYS`, so a large
+ * production database is walked in bounded batches.
+ */
+export function createRedis(url) {
+    return new Redis(url, {
+        lazyConnect: true,
+        maxRetriesPerRequest: 3,
+        enableReadyCheck: true,
+    });
+}
+/**
+ * Iterates keys matching a pattern with `SCAN`, collecting the results. Uses a
+ * generous `COUNT` hint but never blocks Redis the way `KEYS` would.
+ */
+export async function scanKeys(redis, match, count = 500) {
+    const found = [];
+    let cursor = "0";
+    do {
+        const [next, batch] = await redis.scan(cursor, "MATCH", match, "COUNT", count);
+        cursor = next;
+        for (const key of batch)
+            found.push(key);
+    } while (cursor !== "0");
+    return found;
+}
+//# sourceMappingURL=redis.js.map

package/dist/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../src/redis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE;QACpB,WAAW,EAAE,IAAI;QACjB,oBAAoB,EAAE,CAAC;QACvB,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAY,EAAE,KAAa,EAAE,KAAK,GAAG,GAAG;IACrE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,MAAM,GAAG,GAAG,CAAC;IACjB,GAAG,CAAC;QACF,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/E,MAAM,GAAG,IAAI,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;IACzB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { BackendRegistry } from "./backends/index.js";
+export interface ServerOptions {
+    registry: BackendRegistry;
+    readOnly: boolean;
+}
+export declare function createServer({ registry, readOnly }: ServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,105 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { BackendError } from "./types.js";
+const SERVER_VERSION = "0.1.0";
+const backendArg = z
+    .enum(["asynq", "bullmq"])
+    .optional()
+    .describe("Which backend owns the queue. Optional when the queue name is unique across backends.");
+const queueArg = z.string().min(1).describe("Queue name, as reported by list_queues.");
+const idArg = z.string().min(1).describe("Job or task id.");
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** Runs a handler, turning known backend errors and connection failures into
+ *  tool errors instead of letting them crash the transport. */
+async function guard(run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (err instanceof BackendError)
+            return fail(`${err.code}: ${err.message}`);
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+export function createServer({ registry, readOnly }) {
+    const server = new McpServer({ name: "queue-inspector-mcp", version: SERVER_VERSION });
+    server.registerTool("list_queues", {
+        title: "List queues",
+        description: "List every queue the inspector can see, tagged with its backend (asynq or bullmq).",
+        inputSchema: { backend: backendArg },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ backend }) => guard(async () => {
+        const queues = await registry.allQueues();
+        const filtered = backend ? queues.filter((q) => q.backend === backend) : queues;
+        return ok({ count: filtered.length, queues: filtered });
+    }));
+    server.registerTool("queue_stats", {
+        title: "Queue stats",
+        description: "Report the number of jobs in each state for a queue, using the backend's own state names.",
+        inputSchema: { queue: queueArg, backend: backendArg },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ queue, backend }) => guard(async () => {
+        const b = await registry.resolve(queue, backend);
+        return ok({ queue, backend: b.name, states: await b.stats(queue) });
+    }));
+    server.registerTool("list_jobs", {
+        title: "List jobs",
+        description: "List jobs in a given state (paged). Returns id, type, attempts and a truncated last error. " +
+            "Valid states depend on the backend: asynq uses pending/active/scheduled/retry/archived/completed; " +
+            "bullmq uses waiting/active/delayed/prioritized/waiting-children/paused/completed/failed.",
+        inputSchema: {
+            queue: queueArg,
+            state: z.string().min(1).describe("State to list, e.g. \"failed\" (bullmq) or \"archived\" (asynq)."),
+            backend: backendArg,
+            offset: z.number().int().min(0).default(0).describe("Number of jobs to skip."),
+            limit: z.number().int().min(1).max(200).default(20).describe("Maximum jobs to return."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ queue, state, backend, offset, limit }) => guard(async () => {
+        const b = await registry.resolve(queue, backend);
+        const jobs = await b.listJobs(queue, state, { offset, limit });
+        return ok({ queue, backend: b.name, state, offset, limit, count: jobs.length, jobs });
+    }));
+    server.registerTool("get_job", {
+        title: "Get job",
+        description: "Fetch full detail for one job: payload, attempts, retry ceiling, last error and timestamps. " +
+            "Binary payloads are returned base64-encoded and flagged.",
+        inputSchema: { queue: queueArg, id: idArg, backend: backendArg },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ queue, id, backend }) => guard(async () => {
+        const b = await registry.resolve(queue, backend);
+        const job = await b.getJob(queue, id);
+        if (!job)
+            return fail(`job_not_found: no job "${id}" in queue "${queue}"`);
+        return ok(job);
+    }));
+    if (!readOnly) {
+        server.registerTool("retry_job", {
+            title: "Retry job",
+            description: "Move a failed or dead job back to the pending/wait queue so it runs again. " +
+                "Faithfully replicates the backend's own retry (asynq Inspector.RunTask, bullmq Job.retry).",
+            inputSchema: { queue: queueArg, id: idArg, backend: backendArg },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async ({ queue, id, backend }) => guard(async () => {
+            const b = await registry.resolve(queue, backend);
+            return ok(await b.retryJob(queue, id));
+        }));
+        server.registerTool("delete_job", {
+            title: "Delete job",
+            description: "Permanently delete a job from a queue. Active jobs cannot be deleted. " +
+                "Faithfully replicates the backend's own delete (asynq Inspector.DeleteTask, bullmq Job.remove).",
+            inputSchema: { queue: queueArg, id: idArg, backend: backendArg },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        }, async ({ queue, id, backend }) => guard(async () => {
+            const b = await registry.resolve(queue, backend);
+            return ok(await b.deleteJob(queue, id));
+        }));
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type BackendName = "asynq" | "bullmq";
+export interface QueueRef {
+    name: string;
+    backend: BackendName;
+}
+/** Counts keyed by each backend's own state names. */
+export type StateCounts = Record<string, number>;
+export interface JobSummary {
+    id: string;
+    /** Asynq task type or BullMQ job name. */
+    type: string;
+    /** The backend's own state name (e.g. "retry", "archived", "failed"). */
+    state: string;
+    /** ISO 8601, or null when the backend does not record an enqueue time. */
+    enqueuedAt: string | null;
+    /** Retries performed so far (Asynq `retried`, BullMQ `attemptsMade`). */
+    attempts: number | null;
+    /** Configured retry ceiling (Asynq `retry`, BullMQ `opts.attempts`). */
+    maxRetries: number | null;
+    /** Last failure message, truncated for list views. */
+    lastError: string | null;
+}
+export interface JobDetail extends JobSummary {
+    queue: string;
+    backend: BackendName;
+    /** Payload decoded as UTF-8 text, or base64 when the bytes are not valid text. */
+    payload: string;
+    payloadEncoding: "utf8" | "base64";
+    /** Size of the original payload in bytes, before any truncation. */
+    payloadBytes: number;
+    payloadTruncated: boolean;
+    /** Backend-specific timestamps (ISO 8601), null when not set. */
+    timestamps: Record<string, string | null>;
+    /** Full, untruncated last failure message. */
+    fullError: string | null;
+}
+export interface PageOpts {
+    offset: number;
+    limit: number;
+}
+export interface MutationResult {
+    ok: true;
+    message: string;
+}
+export interface QueueBackend {
+    readonly name: BackendName;
+    /** State names this backend reports, in a sensible display order. */
+    readonly states: readonly string[];
+    detectQueues(): Promise<string[]>;
+    stats(queue: string): Promise<StateCounts>;
+    listJobs(queue: string, state: string, page: PageOpts): Promise<JobSummary[]>;
+    getJob(queue: string, id: string): Promise<JobDetail | null>;
+    retryJob(queue: string, id: string): Promise<MutationResult>;
+    deleteJob(queue: string, id: string): Promise<MutationResult>;
+}
+/**
+ * Raised for conditions a caller can act on: an unknown queue or job, or a job
+ * whose current state does not allow the requested operation. The server turns
+ * these into tool errors rather than crashing.
+ */
+export declare class BackendError extends Error {
+    readonly code: "queue_not_found" | "job_not_found" | "invalid_state" | "not_allowed";
+    constructor(message: string, code: "queue_not_found" | "job_not_found" | "invalid_state" | "not_allowed");
+}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Raised for conditions a caller can act on: an unknown queue or job, or a job
+ * whose current state does not allow the requested operation. The server turns
+ * these into tool errors rather than crashing.
+ */
+export class BackendError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "BackendError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA+DA;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAG1B;IAFX,YACE,OAAe,EACN,IAIQ;QAEjB,KAAK,CAAC,OAAO,CAAC,CAAC;QANN,SAAI,GAAJ,IAAI,CAII;QAGjB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "queue-inspector-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.yusufihsangorgel/queue-inspector-mcp",
+  "description": "MCP server for inspecting and operating Redis-backed job queues (Asynq and BullMQ).",
+  "type": "module",
+  "bin": {
+    "queue-inspector-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "redis",
+    "queue",
+    "bullmq",
+    "asynq",
+    "jobs"
+  ],
+  "author": "Yusuf İhsan Görgel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Yusufihsangorgel/queue-inspector-mcp"
+  },
+  "homepage": "https://github.com/Yusufihsangorgel/queue-inspector-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Yusufihsangorgel/queue-inspector-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "ioredis": "^5.4.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}