@michaelbel/cuckcoder-mcp 1.6.11

package/dist/source/github.js

@@ -0,0 +1,185 @@
+import { getServerName, getServerVersion } from "../version.js";
+import { WorkflowError } from "../errors.js";
+import { BoundedTtlCache, RequestDeduplicator } from "./cache.js";
+const BASE_RAW = "https://raw.githubusercontent.com";
+const BASE_API = "https://api.github.com";
+/** Per-request timeout. */
+export const GITHUB_TIMEOUT_MS = 10_000;
+/** Total attempts (1 initial + up to 2 retries). */
+export const GITHUB_MAX_ATTEMPTS = 3;
+/** Base delay for exponential backoff between retries, when the server gives no Retry-After. */
+export const GITHUB_RETRY_BASE_DELAY_MS = 300;
+/** Cap on a `git/trees` API response body. */
+export const GITHUB_TREE_MAX_BYTES = 5 * 1024 * 1024;
+/** Cap on a single raw markdown file body. */
+export const GITHUB_FILE_MAX_BYTES = 1 * 1024 * 1024;
+/** How long a successful response is considered fresh. */
+export const GITHUB_CACHE_TTL_MS = 10 * 60 * 1000;
+/** Bounded cache size (per cache instance), oldest entry evicted once exceeded. */
+export const GITHUB_CACHE_MAX_ENTRIES = 200;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRetryAfterMs(res) {
+    const header = res.headers.get("retry-after");
+    if (!header) {
+        return undefined;
+    }
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const dateMs = Date.parse(header);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return undefined;
+}
+/**
+ * Hardened GitHub HTTP client for the optional remote source mode: bounded timeout, bounded
+ * retry (only for transport errors, 429, and 5xx — never for a plain 4xx like 404/403), honors
+ * `Retry-After`, caps response size, and never logs the token (it only ever goes into the
+ * `Authorization` header of the outgoing request).
+ */
+export class GithubClient {
+    options;
+    fetchImpl;
+    timeoutMs;
+    maxAttempts;
+    treeMaxBytes;
+    fileMaxBytes;
+    fileCache;
+    treeCache;
+    fileDedup = new RequestDeduplicator();
+    treeDedup = new RequestDeduplicator();
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? GITHUB_TIMEOUT_MS;
+        this.maxAttempts = options.maxAttempts ?? GITHUB_MAX_ATTEMPTS;
+        this.treeMaxBytes = options.treeMaxBytes ?? GITHUB_TREE_MAX_BYTES;
+        this.fileMaxBytes = options.fileMaxBytes ?? GITHUB_FILE_MAX_BYTES;
+        const ttlMs = options.cacheTtlMs ?? GITHUB_CACHE_TTL_MS;
+        const maxEntries = options.cacheMaxEntries ?? GITHUB_CACHE_MAX_ENTRIES;
+        this.fileCache = new BoundedTtlCache({ ttlMs, maxEntries });
+        this.treeCache = new BoundedTtlCache({ ttlMs, maxEntries });
+    }
+    authHeaders() {
+        const headers = {
+            "User-Agent": `${getServerName()}/${getServerVersion()}`,
+            Accept: "application/vnd.github+json",
+        };
+        if (this.options.token) {
+            headers.Authorization = `Bearer ${this.options.token}`;
+        }
+        return headers;
+    }
+    async requestText(url, headers, maxBytes) {
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            const controller = new AbortController();
+            const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const res = await this.fetchImpl(url, { headers, signal: controller.signal });
+                clearTimeout(timeoutHandle);
+                if (res.status === 404) {
+                    throw new WorkflowError("NOT_FOUND", `GitHub resource not found (HTTP 404).`, { retryable: false });
+                }
+                if (res.status === 429) {
+                    if (attempt < this.maxAttempts) {
+                        await delay(parseRetryAfterMs(res) ?? GITHUB_RETRY_BASE_DELAY_MS * attempt);
+                        continue;
+                    }
+                    throw new WorkflowError("GITHUB_RATE_LIMITED", "GitHub API rate limit exceeded.", { retryable: true });
+                }
+                if (res.status >= 500 && res.status < 600) {
+                    if (attempt < this.maxAttempts) {
+                        await delay(parseRetryAfterMs(res) ?? GITHUB_RETRY_BASE_DELAY_MS * attempt);
+                        continue;
+                    }
+                    throw new WorkflowError("GITHUB_UNREACHABLE", `GitHub API returned HTTP ${res.status}.`, {
+                        retryable: true,
+                    });
+                }
+                if (!res.ok) {
+                    // A definitive, non-retryable 4xx (401/403/etc). Retrying with the same request will
+                    // not succeed, so this is not retryable even though the code is GITHUB_UNREACHABLE.
+                    throw new WorkflowError("GITHUB_UNREACHABLE", `GitHub API returned HTTP ${res.status}.`, {
+                        retryable: false,
+                    });
+                }
+                const text = await res.text();
+                if (Buffer.byteLength(text, "utf8") > maxBytes) {
+                    throw new WorkflowError("RESPONSE_TOO_LARGE", `GitHub response exceeded the ${maxBytes}-byte limit.`, {
+                        retryable: false,
+                    });
+                }
+                return text;
+            }
+            catch (error) {
+                clearTimeout(timeoutHandle);
+                if (error instanceof WorkflowError) {
+                    if (!error.retryable || attempt >= this.maxAttempts) {
+                        throw error;
+                    }
+                    lastError = error;
+                    await delay(GITHUB_RETRY_BASE_DELAY_MS * attempt);
+                    continue;
+                }
+                const isAbort = error instanceof Error && error.name === "AbortError";
+                lastError = new WorkflowError(isAbort ? "GITHUB_TIMEOUT" : "GITHUB_UNREACHABLE", isAbort ? "GitHub request timed out." : `GitHub request failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+                if (attempt >= this.maxAttempts) {
+                    throw lastError;
+                }
+                await delay(GITHUB_RETRY_BASE_DELAY_MS * attempt);
+            }
+        }
+        throw lastError instanceof Error ? lastError : new WorkflowError("GITHUB_UNREACHABLE", "GitHub request failed.");
+    }
+    async fetchFile(ref, path) {
+        const cacheKey = `${ref}:${path}`;
+        const cached = this.fileCache.get(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        return this.fileDedup.run(cacheKey, async () => {
+            const url = `${BASE_RAW}/${this.options.owner}/${this.options.repo}/${ref}/${path}`;
+            try {
+                const text = await this.requestText(url, this.authHeaders(), this.fileMaxBytes);
+                this.fileCache.set(cacheKey, text);
+                return text;
+            }
+            catch (error) {
+                const stale = this.fileCache.getStale(cacheKey);
+                if (stale !== undefined && error instanceof WorkflowError && error.code !== "NOT_FOUND") {
+                    return stale;
+                }
+                throw error;
+            }
+        });
+    }
+    async listTree(ref) {
+        const cacheKey = ref;
+        const cached = this.treeCache.get(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        return this.treeDedup.run(cacheKey, async () => {
+            const url = `${BASE_API}/repos/${this.options.owner}/${this.options.repo}/git/trees/${ref}?recursive=1`;
+            try {
+                const text = await this.requestText(url, this.authHeaders(), this.treeMaxBytes);
+                const data = JSON.parse(text);
+                const tree = data.tree ?? [];
+                this.treeCache.set(cacheKey, tree);
+                return tree;
+            }
+            catch (error) {
+                const stale = this.treeCache.getStale(cacheKey);
+                if (stale !== undefined && error instanceof WorkflowError && error.code !== "NOT_FOUND") {
+                    return stale;
+                }
+                throw error;
+            }
+        });
+    }
+}

package/dist/source/index.js

@@ -0,0 +1,36 @@
+import { WorkflowError } from "../errors.js";
+import { getServerVersion } from "../version.js";
+import { BundledSource } from "./bundled.js";
+import { GithubSource } from "./github-source.js";
+export { BundledSource } from "./bundled.js";
+export { GithubSource } from "./github-source.js";
+/** `mcp-v1.2.3` — an immutable release tag, never `main`/`master`. */
+const TAG_REF_PATTERN = /^mcp-v\d+\.\d+\.\d+$/;
+/** A full 40-hex-character commit SHA. */
+const SHA_REF_PATTERN = /^[0-9a-f]{40}$/;
+export function defaultGithubRef() {
+    return `mcp-v${getServerVersion()}`;
+}
+/**
+ * Validates a ref intended for the optional GitHub source mode. Only an immutable release tag
+ * (`mcp-v<semver>`) or a full commit SHA is accepted — `main`, `master`, short SHAs, branch
+ * names, and anything else are rejected so the server can never be pointed at a moving target.
+ */
+export function validateGithubRef(ref) {
+    if (TAG_REF_PATTERN.test(ref) || SHA_REF_PATTERN.test(ref)) {
+        return ref;
+    }
+    throw new WorkflowError("INVALID_SOURCE_REF", `Invalid AI_WORKFLOW_GITHUB_REF '${ref}'. Expected an immutable tag like 'mcp-v1.2.3' or a full 40-character commit SHA.`);
+}
+/**
+ * Picks the WorkflowSource implementation from environment variables. Bundled (no network) is
+ * the default; GitHub mode is opt-in via `AI_WORKFLOW_SOURCE=github` and always resolves to a
+ * validated immutable ref, never the mutable `main` branch.
+ */
+export function createSource(env, fetchImpl) {
+    if (env.AI_WORKFLOW_SOURCE === "github") {
+        const ref = validateGithubRef(env.AI_WORKFLOW_GITHUB_REF ?? defaultGithubRef());
+        return new GithubSource(ref, env.GITHUB_TOKEN, fetchImpl);
+    }
+    return new BundledSource(defaultGithubRef());
+}

package/dist/source/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.js

@@ -0,0 +1,33 @@
+import { WorkflowError } from "./errors.js";
+const DEPRECATED_SKILL_SUFFIX = "/SKILL";
+/**
+ * Pure kebab-case skill directory name: lowercase alphanumeric segments separated by `-`.
+ * No slash, dot, backslash, underscore, uppercase letter, or whitespace can appear, which is
+ * sufficient to make path traversal (`..`, `/`, absolute paths) impossible.
+ */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Rule name: the lowercase kebab-case basename without `.md`, e.g. `mvi-error-handling`.
+ * Slashes, dots, backslashes, underscores and uppercase letters cannot match, so path traversal
+ * is impossible.
+ */
+const RULE_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Validates a skill name from an MCP caller. Accepts the deprecated `<name>/SKILL` alias (stripped
+ * before validation) for backward compatibility, but the returned value is always the bare name.
+ */
+export function validateSkillName(rawName) {
+    const name = rawName.endsWith(DEPRECATED_SKILL_SUFFIX)
+        ? rawName.slice(0, -DEPRECATED_SKILL_SUFFIX.length)
+        : rawName;
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        throw new WorkflowError("INVALID_NAME", `Invalid skill name '${rawName}'. Expected a kebab-case skill directory name, e.g. 'create-feature-scaffold-screen'.`);
+    }
+    return name;
+}
+export function validateRuleName(rawName) {
+    if (!RULE_NAME_PATTERN.test(rawName)) {
+        throw new WorkflowError("INVALID_NAME", `Invalid rule name '${rawName}'. Expected a lowercase kebab-case rule name, e.g. 'mvi-error-handling'.`);
+    }
+    return rawName;
+}

package/dist/version.js

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedPackageJson;
+/**
+ * Resolves mcp/package.json relative to the currently running module file. This works
+ * identically whether the module is executing as `src/version.ts` (via tsx, one directory below
+ * mcp/) or as the compiled `dist/version.js` (also one directory below mcp/) — so there is a
+ * single source of truth for the package version and no separate literal to keep in sync.
+ */
+export function readPackageJson() {
+    if (cachedPackageJson) {
+        return cachedPackageJson;
+    }
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = join(moduleDir, "..", "package.json");
+    const raw = readFileSync(packageJsonPath, "utf8");
+    cachedPackageJson = JSON.parse(raw);
+    return cachedPackageJson;
+}
+export function getServerVersion() {
+    return readPackageJson().version;
+}
+export function getServerName() {
+    return readPackageJson().name;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@michaelbel/cuckcoder-mcp",
+  "version": "1.6.11",
+  "description": "MCP server for Cuckcoder rules and skills",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "cuckcoder-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "copy-assets": "tsx scripts/copy-assets.ts",
+    "build": "npm run copy-assets && tsc",
+    "dev": "npm run copy-assets && tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run copy-assets && tsx --test \"test/**/*.test.ts\"",
+    "validate": "tsx scripts/validate.ts",
+    "smoke": "tsx scripts/smoke.ts",
+    "check": "npm run validate && npm test && npm run build && npm run smoke && npm pack --dry-run",
+    "prepack": "npm run build",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist/",
+    "assets/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}