@thallylabs/mcp 0.7.0

package/dist/track.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The branch prefix the docs agent stamps on its own PRs (`run.ts` creates
+ * `thally/agent-<base36>`). Track's loop guard ignores PRs from these branches so a
+ * self-tracking repo never chases its own agent PRs. Single source of truth for
+ * the webhook relay, the scaffolded Actions workflow, and the producer.
+ */
+declare const AGENT_BRANCH_PREFIX = "thally/agent-";
+/** Label that turns an OPEN PR into a preview-docs request (shared by the
+ * webhook relay and the scaffolded sender workflow). */
+declare const DOCS_PREVIEW_LABEL = "docs-preview";
+interface OwnerRepoRef {
+    owner: string;
+    repo: string;
+    /** Present when the spec pinned a PR number (`owner/repo#123`). */
+    pr?: number;
+}
+/**
+ * Parse a tracked-repo spec: `owner/repo`, `owner/repo#123`, or a github.com
+ * URL (`https://github.com/owner/repo(.git)`, optionally `.../pull/123`).
+ * Returns null for anything else.
+ */
+declare function parseOwnerRepo(spec: string): OwnerRepoRef | null;
+interface PrFile {
+    filename: string;
+    /** GitHub status: added | removed | modified | renamed | … */
+    status: string;
+    additions: number;
+    deletions: number;
+    /** Unified diff hunk; absent for binary or very large files. */
+    patch?: string;
+}
+interface PullRequestInfo {
+    number: number;
+    title: string;
+    body: string;
+    htmlUrl: string;
+    /** The branch the PR merged INTO. */
+    baseRef: string;
+    /** The merge commit SHA, when merged. */
+    mergeCommitSha?: string;
+    author?: string;
+}
+/** GitHub App installation credentials (the "Connect GitHub" path). */
+interface GithubAppCreds {
+    appId: string | number;
+    installationId: string | number;
+    /** PEM-encoded private key (PKCS#1 or PKCS#8). */
+    privateKey: string;
+}
+interface GithubFetchOptions {
+    /** Overrides the token resolver entirely. */
+    token?: string;
+    /** GitHub App creds to mint an installation token from (used before the PAT chain). */
+    appCreds?: GithubAppCreds;
+    /** Injectable for tests — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Sign an App-level RS256 JWT (iss = appId) — authenticates AS THE APP for the
+ * App API (installation lookups, token exchange). Lives at most 10 min.
+ */
+declare function createAppJwt(appId: string | number, privateKey: string): string;
+/**
+ * Mint a GitHub App installation access token: sign an App JWT, then exchange it
+ * for a short-lived, repo-scoped installation token. Dependency-free
+ * (node:crypto). Cached per (app, installation, key) — so a key rotation or a
+ * reconnect never serves a token minted from stale credentials.
+ */
+declare function mintInstallationToken(creds: GithubAppCreds, fetchImpl?: typeof fetch): Promise<string>;
+/**
+ * Confirm an installation id genuinely belongs to this app (authenticated as the
+ * app). Used by the "Connect GitHub" callback to accept a post-install
+ * `installation_id` WITHOUT trusting the query param alone — an attacker-forged
+ * or foreign id fails this check, closing the CSRF hole on the install step.
+ */
+declare function verifyInstallationBelongsToApp(appId: string | number, privateKey: string, installationId: string | number, fetchImpl?: typeof fetch): Promise<boolean>;
+/**
+ * Resolve a GitHub API token. Precedence: an explicit token → a GitHub App
+ * installation token (passed creds, then env creds) → the personal-token chain
+ * (`THALLY_GITHUB_TOKEN → THALLY_TASKS_TOKEN → GH_TOKEN → GITHUB_TOKEN`, each
+ * `THALLY_*` falling back to its legacy `DOX_*` name). One resolver
+ * for every Track call site so the chain never drifts.
+ */
+declare function resolveGithubToken(options?: GithubFetchOptions): Promise<string | undefined>;
+/** Fetch a pull request's metadata. */
+declare function fetchPullRequest(owner: string, repo: string, number: number, options?: GithubFetchOptions): Promise<PullRequestInfo>;
+/** Fetch a pull request's changed files with per-file patches (one page, up to 100). */
+declare function fetchPullRequestFiles(owner: string, repo: string, number: number, options?: GithubFetchOptions): Promise<Array<PrFile>>;
+/**
+ * The most recent MERGED pull request into `base`, or null when there is none.
+ * Used by `thally track test` / `sync_from_repo` to preview "the latest merge".
+ */
+declare function fetchLatestMergedPr(owner: string, repo: string, base: string, options?: GithubFetchOptions): Promise<PullRequestInfo | null>;
+/** Single glob check (compiles on each call — use filterFilesByGlobs for many files). */
+declare function matchesGlob(pattern: string, filePath: string): boolean;
+/**
+ * Filter files by path globs; absent/empty globs match everything. Each glob is
+ * compiled once (M compilations), not once per file (N×M) — matters on large
+ * PRs handled in the webhook request path.
+ */
+declare function filterFilesByGlobs<T extends {
+    filename: string;
+}>(files: Array<T>, globs?: Array<string>): Array<T>;
+interface TrackedRepoLike {
+    owner: string;
+    repo: string;
+    /** The base branch PRs must merge into to trigger (default "main"). */
+    branch?: string;
+    paths?: Array<string>;
+    outputTab?: string;
+    outputGroup?: string;
+}
+/** Same context budget the agent's other context builders use. */
+declare const TRACK_CONTEXT_CHAR_CAP = 20000;
+/**
+ * The one-line instruction for a merged tracked PR. Pure (no network) and free
+ * of shell-metacharacter wrapping — it is dispatched through GitHub Actions
+ * where it lands in a shell, so it must never embed quotes that could break (or
+ * be injected into) the run script; the receiver reads it from an env var. The
+ * PR title is NOT embedded (it's attacker-influenced and the docs-repo Action
+ * rebuilds full context from --from-pr anyway).
+ *
+ * The instruction frames the agent's actual job: judge what user-facing
+ * behavior the merged PR changed and update the docs that describe it.
+ */
+declare function buildTrackInstruction(repo: TrackedRepoLike, pr: Pick<PullRequestInfo, 'number'>, options?: {
+    preview?: boolean;
+}): string;
+/** The capped markdown context for a merged tracked PR (title, body, file diffs). */
+declare function buildTrackContext(repo: Pick<TrackedRepoLike, 'owner' | 'repo'>, pr: PullRequestInfo, files: Array<PrFile>): string;
+/**
+ * Distill a merged PR into the docs task the agent runs: a one-line instruction
+ * (output routing) and a capped markdown context (PR description + diff).
+ */
+declare function buildTrackTask(repo: TrackedRepoLike, pr: PullRequestInfo, files: Array<PrFile>): {
+    instruction: string;
+    context: string;
+};
+
+export { AGENT_BRANCH_PREFIX, DOCS_PREVIEW_LABEL, type GithubAppCreds, type GithubFetchOptions, type OwnerRepoRef, type PrFile, type PullRequestInfo, TRACK_CONTEXT_CHAR_CAP, type TrackedRepoLike, buildTrackContext, buildTrackInstruction, buildTrackTask, createAppJwt, fetchLatestMergedPr, fetchPullRequest, fetchPullRequestFiles, filterFilesByGlobs, matchesGlob, mintInstallationToken, parseOwnerRepo, resolveGithubToken, verifyInstallationBelongsToApp };

package/dist/track.js

@@ -0,0 +1,219 @@
+// src/lib/track.ts
+import { createSign, createHash } from "crypto";
+var AGENT_BRANCH_PREFIX = "thally/agent-";
+var DOCS_PREVIEW_LABEL = "docs-preview";
+function parseOwnerRepo(spec) {
+  const trimmed = spec.trim();
+  const url = trimmed.match(
+    /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:\/pull\/(\d+))?(?:[/#?].*)?$/i
+  );
+  if (url) return { owner: url[1], repo: url[2], ...url[3] ? { pr: Number(url[3]) } : {} };
+  const plain = trimmed.match(/^([A-Za-z0-9-_.]+)\/([A-Za-z0-9-_.]+?)(?:#(\d+))?$/);
+  if (!plain) return null;
+  return { owner: plain[1], repo: plain[2], ...plain[3] ? { pr: Number(plain[3]) } : {} };
+}
+function base64url(input) {
+  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+var installationTokenCache = /* @__PURE__ */ new Map();
+function createAppJwt(appId, privateKey) {
+  const now = Math.floor(Date.now() / 1e3);
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64url(JSON.stringify({ iat: now - 60, exp: now + 9 * 60, iss: String(appId) }));
+  const signature = base64url(createSign("RSA-SHA256").update(`${header}.${payload}`).sign(privateKey));
+  return `${header}.${payload}.${signature}`;
+}
+async function mintInstallationToken(creds, fetchImpl = fetch) {
+  const keyFp = createHash("sha256").update(creds.privateKey).digest("hex").slice(0, 12);
+  const cacheKey = `${creds.appId}:${creds.installationId}:${keyFp}`;
+  const cached = installationTokenCache.get(cacheKey);
+  if (cached && cached.expiresAtMs - 6e4 > Date.now()) return cached.token;
+  const jwt = createAppJwt(creds.appId, creds.privateKey);
+  const res = await fetchImpl(`https://api.github.com/app/installations/${creds.installationId}/access_tokens`, {
+    method: "POST",
+    headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${jwt}` }
+  });
+  if (!res.ok) {
+    throw new Error(`GitHub App token exchange failed (${res.status}) \u2014 check the app id, installation id, and private key.`);
+  }
+  const body = await res.json();
+  const parsed = Date.parse(body.expires_at);
+  const expiresAtMs = Number.isFinite(parsed) ? parsed : Date.now() + 30 * 60 * 1e3;
+  installationTokenCache.set(cacheKey, { token: body.token, expiresAtMs });
+  return body.token;
+}
+async function verifyInstallationBelongsToApp(appId, privateKey, installationId, fetchImpl = fetch) {
+  const jwt = createAppJwt(appId, privateKey);
+  const res = await fetchImpl(`https://api.github.com/app/installations/${installationId}`, {
+    headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${jwt}` }
+  });
+  if (!res.ok) return false;
+  const body = await res.json();
+  return String(body.app_id) === String(appId);
+}
+function envAppCreds() {
+  const appId = (process.env.THALLY_GITHUB_APP_ID ?? process.env.DOX_GITHUB_APP_ID)?.trim();
+  const installationId = (process.env.THALLY_GITHUB_APP_INSTALLATION_ID ?? process.env.DOX_GITHUB_APP_INSTALLATION_ID)?.trim();
+  const privateKey = process.env.THALLY_GITHUB_APP_PRIVATE_KEY ?? process.env.DOX_GITHUB_APP_PRIVATE_KEY;
+  if (appId && installationId && privateKey) return { appId, installationId, privateKey };
+  return void 0;
+}
+async function resolveGithubToken(options) {
+  if (options?.token) return options.token;
+  const pat = process.env.THALLY_GITHUB_TOKEN ?? process.env.DOX_GITHUB_TOKEN ?? process.env.THALLY_TASKS_TOKEN ?? process.env.DOX_TASKS_TOKEN ?? process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? void 0;
+  const appCreds = options?.appCreds ?? envAppCreds();
+  if (appCreds) {
+    try {
+      return await mintInstallationToken(appCreds, options?.fetchImpl ?? fetch);
+    } catch (err) {
+      console.warn(`[thally-track] GitHub App token mint failed, falling back to PAT: ${err instanceof Error ? err.message : String(err)}`);
+      return pat;
+    }
+  }
+  return pat;
+}
+async function githubJson(path, options) {
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const token = await resolveGithubToken(options);
+  const headers = { Accept: "application/vnd.github+json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const response = await fetchImpl(`https://api.github.com${path}`, { headers });
+  if (!response.ok) {
+    const hint = response.status === 404 || response.status === 403 ? " (private repo or rate limit? set THALLY_GITHUB_TOKEN or connect a GitHub App)" : "";
+    throw new Error(`GitHub API ${response.status} for ${path}${hint}`);
+  }
+  return await response.json();
+}
+function toPullRequestInfo(raw) {
+  return {
+    number: raw.number,
+    title: raw.title ?? "",
+    body: raw.body ?? "",
+    htmlUrl: raw.html_url ?? "",
+    baseRef: raw.base?.ref ?? "main",
+    ...raw.merge_commit_sha ? { mergeCommitSha: raw.merge_commit_sha } : {},
+    ...raw.user?.login ? { author: raw.user.login } : {}
+  };
+}
+async function fetchPullRequest(owner, repo, number, options) {
+  const raw = await githubJson(`/repos/${owner}/${repo}/pulls/${number}`, options);
+  return toPullRequestInfo(raw);
+}
+async function fetchPullRequestFiles(owner, repo, number, options) {
+  const perPage = 100;
+  const maxPages = 30;
+  const raw = [];
+  for (let page = 1; page <= maxPages; page++) {
+    const chunk = await githubJson(`/repos/${owner}/${repo}/pulls/${number}/files?per_page=${perPage}&page=${page}`, options);
+    raw.push(...chunk);
+    if (chunk.length < perPage) break;
+  }
+  return raw.map((f) => ({
+    filename: f.filename,
+    status: f.status,
+    additions: f.additions,
+    deletions: f.deletions,
+    ...f.patch ? { patch: f.patch } : {}
+  }));
+}
+async function fetchLatestMergedPr(owner, repo, base, options) {
+  const raw = await githubJson(
+    `/repos/${owner}/${repo}/pulls?state=closed&base=${encodeURIComponent(base)}&sort=updated&direction=desc&per_page=30`,
+    options
+  );
+  const merged = raw.filter((pr) => Boolean(pr.merged_at)).sort((a, b) => Date.parse(b.merged_at ?? "") - Date.parse(a.merged_at ?? ""))[0];
+  return merged ? toPullRequestInfo(merged) : null;
+}
+function compileGlob(pattern) {
+  const normalized = pattern.replace(/^\.\//, "");
+  let regex = "";
+  for (let i = 0; i < normalized.length; i++) {
+    const char = normalized[i];
+    if (char === "*") {
+      if (normalized[i + 1] === "*") {
+        if (normalized[i + 2] === "/") {
+          regex += "(?:[^/]+/)*";
+          i += 2;
+        } else {
+          regex += ".*";
+          i += 1;
+        }
+      } else {
+        regex += "[^/]*";
+      }
+    } else if (char === "?") {
+      regex += "[^/]";
+    } else {
+      regex += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${regex}$`);
+}
+function matchesGlob(pattern, filePath) {
+  return compileGlob(pattern).test(filePath.replace(/^\.\//, ""));
+}
+function filterFilesByGlobs(files, globs) {
+  if (!globs || globs.length === 0) return files;
+  const compiled = globs.map(compileGlob);
+  return files.filter((file) => {
+    const path = file.filename.replace(/^\.\//, "");
+    return compiled.some((re) => re.test(path));
+  });
+}
+var TRACK_CONTEXT_CHAR_CAP = 2e4;
+function buildTrackInstruction(repo, pr, options) {
+  const placement = repo.outputTab ? ` If new pages are warranted, add them under the ${repo.outputTab} tab${repo.outputGroup ? ` (${repo.outputGroup} group)` : ""}.` : "";
+  const lead = options?.preview ? `An OPEN pull request in ${repo.owner}/${repo.repo} (#${pr.number}) is up for review.` : `A pull request merged in ${repo.owner}/${repo.repo} (#${pr.number}).`;
+  const tail = options?.preview ? ` This is a preview: the PR may still change before it merges, so draft the docs it will need for review alongside it.` : ` Make no change if the PR has no user-facing impact.`;
+  return `${lead} Review it and decide what user-facing behavior it changes (API surface, config, CLI, defaults, behavior). Then find the documentation pages that describe that behavior and update them so the docs match \u2014 editing existing pages in place where they already cover it.${placement}` + tail;
+}
+function buildTrackContext(repo, pr, files) {
+  const header = [
+    `# Merged PR ${repo.owner}/${repo.repo}#${pr.number}: ${pr.title}`,
+    pr.author ? `Author: ${pr.author}` : null,
+    pr.htmlUrl ? `URL: ${pr.htmlUrl}` : null,
+    "",
+    pr.body?.trim() || "(no description)",
+    ""
+  ].filter((line) => line !== null).join("\n");
+  const NOTE_RESERVE = 100;
+  let context = header;
+  for (const file of files) {
+    const section = [
+      `### ${file.filename} (${file.status}, +${file.additions}/-${file.deletions})`,
+      file.patch ? `\`\`\`diff
+${file.patch}
+\`\`\`` : "_(no text diff \u2014 binary or too large)_",
+      ""
+    ].join("\n");
+    if (context.length + section.length > TRACK_CONTEXT_CHAR_CAP - NOTE_RESERVE) {
+      context += `
+_(diff truncated \u2014 ${files.length} file(s) total)_
+`;
+      break;
+    }
+    context += section;
+  }
+  return context.slice(0, TRACK_CONTEXT_CHAR_CAP);
+}
+function buildTrackTask(repo, pr, files) {
+  return { instruction: buildTrackInstruction(repo, pr), context: buildTrackContext(repo, pr, files) };
+}
+export {
+  AGENT_BRANCH_PREFIX,
+  DOCS_PREVIEW_LABEL,
+  TRACK_CONTEXT_CHAR_CAP,
+  buildTrackContext,
+  buildTrackInstruction,
+  buildTrackTask,
+  createAppJwt,
+  fetchLatestMergedPr,
+  fetchPullRequest,
+  fetchPullRequestFiles,
+  filterFilesByGlobs,
+  matchesGlob,
+  mintInstallationToken,
+  parseOwnerRepo,
+  resolveGithubToken,
+  verifyInstallationBelongsToApp
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@thallylabs/mcp",
+  "version": "0.7.0",
+  "description": "MCP server for scaffolding and managing Thally documentation projects",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "thally-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./package.json": "./package.json",
+    "./track": {
+      "types": "./dist/track.d.ts",
+      "import": "./dist/track.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.36.0",
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "gray-matter": "^4.0.3",
+    "p-limit": "^6.1.0",
+    "tar": "^6.2.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/tar": "^6.1.13",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "thally",
+    "documentation",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "llm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thallylabs/thally.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/thallylabs/thally#readme",
+  "bugs": {
+    "url": "https://github.com/thallylabs/thally/issues"
+  }
+}