@ahood/cli 0.5.2 → 0.6.0

package/README.md

@@ -201,6 +201,7 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood whoami [--json]` | Reports whether your stored token still authenticates. |
 | `ahood token create <name>\|list [--json]\|revoke <id> [--yes]` | Manage personal API tokens. |
 | `ahood completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |
+| `ahood mcp` | Start an MCP server exposing read-only skill commands as tools over stdio. |
 
 ### Skill
 
@@ -273,6 +274,7 @@ ahood completion fish > ~/.config/fish/completions/ahood.fish
 - **Structured output everywhere.** `--json` is available on every read command and on `publish`/`update`, so an agent never has to scrape human-formatted text.
 - **Predictable failure.** A stable, documented [exit code](#exit-codes) per failure class, and error messages that never leak raw upstream infrastructure details — safe to surface directly to an agent's reasoning loop.
 - **A real "start here."** `ahood skill init <name>` scaffolds a valid `SKILL.md` an agent can extend, rather than requiring it to know the frontmatter format up front.
+- **A native MCP server, for agents that prefer tool calls to subprocess parsing.** `ahood mcp` starts a Model Context Protocol server over stdio, exposing `skill_search`, `skill_view`, `skill_read`, `skill_versions`, `skill_list`, and `whoami` as typed tools -- the same data the `--json` flags above already return, reachable as structured tool calls instead. Configure your MCP-aware agent host to run `ahood mcp` (or `npx @ahood/cli@latest mcp`) as a stdio server.
 
 ## Development
 

package/dist/commands/list.js

@@ -1,7 +1,11 @@
 import { apiJson } from "../http.js";
+export async function listOwnSkills() {
+    const { skills } = await apiJson("/api/v1/skills?mine=true");
+    return skills ?? [];
+}
 export async function listSkills(args = []) {
     const jsonOutput = args.includes("--json");
-    const { skills } = await apiJson("/api/v1/skills?mine=true");
+    const skills = await listOwnSkills();
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;

package/dist/commands/mcp.js

@@ -0,0 +1,7 @@
+import { startMcpServer } from "../mcp/server.js";
+// `ahood mcp` takes no subcommands/flags in v1. Unlike every other
+// account-scoped command it never returns until the client disconnects --
+// see startMcpServer's comment.
+export async function mcp(_args) {
+    await startMcpServer();
+}

package/dist/commands/read.js

@@ -2,19 +2,16 @@ import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
-export async function read(args) {
-    const jsonOutput = args.includes("--json");
-    const spec = args.find((a) => !a.startsWith("--"));
-    if (!spec)
-        throw new UsageError(USAGE);
-    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+export async function readSkillMd(owner, skill) {
     const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
     if (!detail.skill_versions) {
         throw new Error(`${owner}/${skill} has no published version.`);
     }
     // Mirrors view.ts's exact wording/tone for the same warning -- this
     // command reads straight from the same endpoint/version, so it must not
-    // be silent about handing back a yanked version's content.
+    // be silent about handing back a yanked version's content. Written to
+    // stderr, not stdout -- safe for MCP callers too (only stdout is reserved
+    // for the JSON-RPC stream).
     if (detail.skill_versions.yanked_at) {
         console.warn(`WARNING: ${detail.owner}/${detail.slug}@${detail.skill_versions.version} has been yanked${detail.skill_versions.yanked_reason ? `: ${detail.skill_versions.yanked_reason}` : "."}`);
     }
@@ -22,8 +19,28 @@ export async function read(args) {
     if (!content) {
         throw new Error(`${owner}/${skill}@${detail.skill_versions.version} has no SKILL.md content available.`);
     }
+    return {
+        version: detail.skill_versions.version,
+        content,
+        // The CLI already warns about a yanked version on stderr above, but an
+        // MCP caller has no visibility into stderr -- unlike skill_view, whose
+        // returned object already surfaces yanked_at/yanked_reason, skill_read
+        // was silently dropping this signal for MCP callers entirely. read()
+        // below still destructures only {version, content} for the CLI's
+        // --json output, so this addition doesn't change that shape.
+        yanked_at: detail.skill_versions.yanked_at ?? null,
+        yanked_reason: detail.skill_versions.yanked_reason ?? null,
+    };
+}
+export async function read(args) {
+    const jsonOutput = args.includes("--json");
+    const spec = args.find((a) => !a.startsWith("--"));
+    if (!spec)
+        throw new UsageError(USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    const { version, content } = await readSkillMd(owner, skill);
     if (jsonOutput) {
-        console.log(JSON.stringify({ version: detail.skill_versions.version, content }));
+        console.log(JSON.stringify({ version, content }));
         return;
     }
     // Plain mode prints the raw content verbatim -- no formatting/labels/

package/dist/commands/search.js

@@ -2,9 +2,16 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill search <query> [--json] [--limit <n>]";
+export async function searchSkills(query, limit) {
+    const qs = new URLSearchParams({ q: query });
+    if (limit !== undefined)
+        qs.set("per_page", String(limit));
+    const { skills } = await apiJson(`/api/v1/skills?${qs}`);
+    return skills ?? [];
+}
 export async function search(args) {
     const jsonOutput = args.includes("--json");
-    const limit = flagValue(args, "--limit");
+    const limitStr = flagValue(args, "--limit");
     const queryParts = args.filter((a, i) => a !== "--json" && a !== "--limit" && args[i - 1] !== "--limit");
     const unknownFlag = queryParts.find((a) => a.startsWith("--"));
     if (unknownFlag)
@@ -12,13 +19,11 @@ export async function search(args) {
     const query = queryParts.join(" ");
     if (!query)
         throw new UsageError(USAGE);
-    if (limit !== undefined && (!/^\d+$/.test(limit) || Number(limit) < 1)) {
-        throw new UsageError(`--limit must be a positive integer (got "${limit}").\n${USAGE}`);
+    if (limitStr !== undefined && (!/^\d+$/.test(limitStr) || Number(limitStr) < 1)) {
+        throw new UsageError(`--limit must be a positive integer (got "${limitStr}").\n${USAGE}`);
     }
-    const qs = new URLSearchParams({ q: query });
-    if (limit !== undefined)
-        qs.set("per_page", limit);
-    const { skills } = await apiJson(`/api/v1/skills?${qs}`);
+    const limit = limitStr !== undefined ? Number(limitStr) : undefined;
+    const skills = await searchSkills(query, limit);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;
@@ -30,7 +35,7 @@ export async function search(args) {
     for (const skill of skills) {
         console.log(`${skill.profiles.username}/${skill.slug} - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads)`);
     }
-    if (limit !== undefined && skills.length >= Number(limit)) {
+    if (limit !== undefined && skills.length >= limit) {
         console.log(`(showing up to ${limit} results -- pass a higher --limit for more)`);
     }
 }

package/dist/commands/versions.js

@@ -14,13 +14,17 @@ function formatSize(bytes) {
     }
     return `${value.toFixed(1)} ${units[unitIndex]}`;
 }
+export async function listSkillVersions(owner, skill) {
+    const { versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
+    return versions ?? [];
+}
 export async function versions(args) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
         throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
-    const { versions: list } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
+    const list = await listSkillVersions(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify(list));
         return;

package/dist/commands/view.js

@@ -23,6 +23,9 @@ function openBrowser(url) {
         console.log(`Open this URL in your browser: ${url}`);
     }
 }
+export async function viewSkill(owner, skill) {
+    return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+}
 export async function view(args) {
     const jsonOutput = args.includes("--json");
     const web = args.includes("--web");
@@ -35,7 +38,7 @@ export async function view(args) {
         openBrowser(url);
         return;
     }
-    const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    const detail = await viewSkill(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify(detail));
         return;

package/dist/commands/whoami.js

@@ -14,29 +14,20 @@ async function fetchProfile() {
         return undefined;
     }
 }
-export async function whoami(args = []) {
-    const wantsJson = args.includes("--json");
+// Pure auth-status check: no console output, no process.exitCode -- callers
+// (the CLI's whoami() below, and the MCP whoami tool) decide how to present
+// each outcome. Never throws; every failure mode is a normal return value.
+export async function checkAuth() {
     const token = resolveToken();
     if (!token) {
-        // Previously exited 0 here, defeating whoami's purpose as a scriptable
-        // auth check -- "no token configured at all" must fail just like "token
-        // rejected by the server" does below. Exit 4 ("authentication required
-        // or rejected"), not the generic 1 -- this is exactly the case the
-        // README's own exit-code table names as the canonical example of 4
-        // (ahood-cli#80).
-        if (wantsJson)
-            console.log(JSON.stringify({ authenticated: false }));
-        else
-            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
-        process.exitCode = 4;
-        return;
+        return { authenticated: false, reason: "not_logged_in" };
     }
     // There is no endpoint that returns an identity for a bearer caller yet, so
-    // whoami can only answer "does this token still authenticate?". It probes
+    // this can only answer "does this token still authenticate?". It probes
     // /api/v1/auth/tokens, which is deliberately session-only (Task 3), and
     // reads the STATUS to tell the two failure modes apart -- swallowing every
-    // error and printing "Authenticated." unconditionally (as this did) meant a
-    // revoked token and a garbage token both reported success with exit code 0.
+    // error and reporting success unconditionally (as this used to) meant a
+    // revoked token and a garbage token both reported success.
     //   403 -> resolveCaller accepted the token, the route then rejected it for
     //          being a token rather than a session. The token is valid.
     //   401 -> resolveCaller could not resolve the token at all: unknown,
@@ -48,38 +39,66 @@ export async function whoami(args = []) {
         // A session-backed caller (only reachable if this ever runs against a
         // cookie-bearing client) -- the token list came back.
         const profile = await fetchProfile();
-        if (wantsJson)
-            console.log(JSON.stringify({ authenticated: true, mode: "session", ...profile }));
-        else
-            console.log(profile ? `Authenticated as ${profile.username}.` : "Authenticated.");
+        return { authenticated: true, mode: "session", profile };
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 403) {
             const profile = await fetchProfile();
-            if (wantsJson)
-                console.log(JSON.stringify({ authenticated: true, mode: "token", ...profile }));
-            else
-                console.log(profile
-                    ? `Authenticated as ${profile.username} (personal API token).`
-                    : "Authenticated with a personal API token.");
-            return;
+            return { authenticated: true, mode: "token", profile };
         }
         if (error instanceof ApiError && error.status === 401) {
-            // Same exit-4 reasoning as the "no token at all" branch above: the
-            // token was rejected by the server, which is the other half of the
-            // README's exit-code-4 definition ("or the token was refused").
-            if (wantsJson)
-                console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
-            else
-                console.error("Not authenticated -- your token is invalid or has been revoked.");
-            process.exitCode = 4;
-            return;
+            return { authenticated: false, reason: "invalid_token" };
         }
         const message = error instanceof Error ? error.message : String(error);
+        return { authenticated: null, error: message };
+    }
+}
+export async function whoami(args = []) {
+    const wantsJson = args.includes("--json");
+    const result = await checkAuth();
+    if (result.authenticated === false && result.reason === "not_logged_in") {
+        // Previously exited 0 here, defeating whoami's purpose as a scriptable
+        // auth check -- "no token configured at all" must fail just like "token
+        // rejected by the server" does below. Exit 4 ("authentication required
+        // or rejected"), not the generic 1 -- this is exactly the case the
+        // README's own exit-code table names as the canonical example of 4
+        // (ahood-cli#80).
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: false }));
+        else
+            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
+        process.exitCode = 4;
+        return;
+    }
+    if (result.authenticated === false && result.reason === "invalid_token") {
+        // Same exit-4 reasoning as the "no token at all" branch above: the
+        // token was rejected by the server, which is the other half of the
+        // README's exit-code-4 definition ("or the token was refused").
         if (wantsJson)
-            console.log(JSON.stringify({ authenticated: null, error: message }));
+            console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
         else
-            console.error(`Could not verify your token: ${message}`);
+            console.error("Not authenticated -- your token is invalid or has been revoked.");
+        process.exitCode = 4;
+        return;
+    }
+    if (result.authenticated === null) {
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: null, error: result.error }));
+        else
+            console.error(`Could not verify your token: ${result.error}`);
         process.exitCode = 1;
+        return;
+    }
+    if (wantsJson) {
+        console.log(JSON.stringify({ authenticated: true, mode: result.mode, ...result.profile }));
+        return;
+    }
+    if (result.mode === "session") {
+        console.log(result.profile ? `Authenticated as ${result.profile.username}.` : "Authenticated.");
+    }
+    else {
+        console.log(result.profile
+            ? `Authenticated as ${result.profile.username} (personal API token).`
+            : "Authenticated with a personal API token.");
     }
 }

package/dist/help.js

@@ -26,6 +26,14 @@ export const TOP_LEVEL_COMMANDS_HELP = [
         desc: "Print a shell completion script for the command names.",
         examples: ["ahood completion bash >> ~/.bashrc"],
     },
+    {
+        usage: "ahood mcp",
+        summary: "Start an MCP server exposing read-only skill commands as tools over stdio.",
+        desc: "Start a Model Context Protocol server over stdio, exposing skill_search, skill_view, skill_read, " +
+            "skill_versions, skill_list, and whoami as MCP tools -- the same data ahood's --json commands already " +
+            "return, reachable as typed tool calls instead of parsed CLI output. Meant to be launched by an " +
+            "MCP-aware agent host (e.g. Claude Code's MCP server configuration), not run interactively.",
+    },
 ];
 export const SKILL_COMMANDS_HELP = [
     {

package/dist/index.js

@@ -18,6 +18,7 @@ import { view } from "./commands/view.js";
 import { read } from "./commands/read.js";
 import { versions } from "./commands/versions.js";
 import { completion } from "./commands/completion.js";
+import { mcp } from "./commands/mcp.js";
 import { init } from "./commands/init.js";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
 import { formatHelp, formatSkillHelp, formatGroupHelp, formatCommandHelp, findCommandHelp } from "./help.js";
@@ -69,6 +70,7 @@ const COMMANDS = {
     whoami,
     token,
     completion,
+    mcp,
     skill: dispatchSkill,
     group: dispatchGroup,
 };

package/dist/mcp/safe-tool.js

@@ -0,0 +1,46 @@
+import { ApiError, NetworkError } from "../http.js";
+import { UsageError } from "../usage-error.js";
+// Mirrors exit-code.ts's exitCodeFor categorization (ahood-cli#83) -- one
+// error taxonomy for both the CLI's exit codes and MCP's error_code field,
+// rather than maintaining two.
+export function errorCodeFor(error) {
+    if (error instanceof UsageError)
+        return "usage_error";
+    if (error instanceof ApiError) {
+        if (error.status === 401 || error.status === 403)
+            return "auth_error";
+        if (error.status === 404)
+            return "not_found";
+        if (error.status >= 500)
+            return "network_error";
+        return "usage_error";
+    }
+    if (error instanceof NetworkError)
+        return "network_error";
+    return "general_error";
+}
+// Wraps an MCP tool's data-fetching logic so a thrown error never crosses
+// the stdio boundary as a raw exception -- caught here and turned into a
+// structured isError result instead. `fn` is the tool's own core function
+// (e.g. searchSkills), already adapted to take the single zod-validated
+// input object each MCP tool callback receives.
+export function safeTool(fn) {
+    return async (input) => {
+        try {
+            const result = await fn(input);
+            // Defensive backstop: JSON.stringify(undefined) evaluates to the JS
+            // value `undefined`, not a string -- if any tool's core function ever
+            // returns undefined (e.g. a malformed API response missing an
+            // expected key), the MCP SDK rejects that as an invalid tool result
+            // and throws a raw protocol-level error instead of the structured
+            // isError result this wrapper exists to guarantee. Coalescing to null
+            // keeps `text` a string no matter what `fn` returns.
+            return { content: [{ type: "text", text: JSON.stringify(result ?? null) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const body = { error: message, error_code: errorCodeFor(error) };
+            return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+        }
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { CLI_VERSION } from "../version.js";
+// Split from startMcpServer so tests can build a server and connect it to an
+// InMemoryTransport instead of real stdio.
+export function buildServer() {
+    const server = new McpServer({ name: "ahood", version: CLI_VERSION });
+    registerTools(server);
+    return server;
+}
+// Connects over stdio and blocks: StdioServerTransport reads process.stdin
+// for the life of the process. This is expected -- an MCP host spawns
+// `ahood mcp` as a long-lived subprocess and talks to it over stdio for as
+// long as the session lasts.
+export async function startMcpServer() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { safeTool } from "./safe-tool.js";
+import { searchSkills } from "../commands/search.js";
+import { viewSkill } from "../commands/view.js";
+import { readSkillMd } from "../commands/read.js";
+import { listSkillVersions } from "../commands/versions.js";
+import { listOwnSkills } from "../commands/list.js";
+import { checkAuth } from "../commands/whoami.js";
+import { validateSegment } from "../spec.js";
+// MCP tool inputs arrive as separate owner/skill zod fields (not a single
+// "<owner>/<skill>" spec string like the CLI's argv), so they bypass
+// parseOwnerSkill entirely and go straight to the core function -- which
+// URL-encodes them and hits the API. Running the same validateSegment checks
+// the CLI gets via parseOwnerSkill here closes that gap: an invalid segment
+// (e.g. "..") or an absurdly long one now fails locally as a UsageError
+// (safeTool maps it to error_code "usage_error") instead of reaching the
+// wire with the caller's bearer token.
+function validateOwnerAndSkill(owner, skill) {
+    const spec = `${owner}/${skill}`;
+    validateSegment(owner, "owner", spec);
+    validateSegment(skill, "skill", spec);
+}
+// Registers every v1 MCP tool. Read-only by design (ahood-cli#83's spec) --
+// each tool wraps the same core function the equivalent `ahood skill <verb>
+// --json` CLI path already calls, so there is exactly one source of truth
+// for what each of these returns.
+export function registerTools(server) {
+    server.registerTool("skill_search", {
+        description: "Search published skills in the ahood registry.",
+        inputSchema: { query: z.string().min(1), limit: z.number().int().positive().optional() },
+    }, safeTool(async ({ query, limit }) => searchSkills(query, limit)));
+    server.registerTool("skill_view", {
+        description: "Show a skill's details (tags, license, homepage, repository, dates, etc.) without installing it.",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return viewSkill(owner, skill);
+    }));
+    server.registerTool("skill_read", {
+        description: "Read a skill's full SKILL.md content without installing it.",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return readSkillMd(owner, skill);
+    }));
+    server.registerTool("skill_versions", {
+        description: "List a skill's published-version history (version, changelog, size, publish date).",
+        inputSchema: { owner: z.string().min(1), skill: z.string().min(1) },
+    }, safeTool(async ({ owner, skill }) => {
+        validateOwnerAndSkill(owner, skill);
+        return listSkillVersions(owner, skill);
+    }));
+    server.registerTool("skill_list", {
+        description: "List the authenticated caller's own skills, public and private.",
+        inputSchema: {},
+    }, safeTool(async () => listOwnSkills()));
+    server.registerTool("whoami", {
+        description: "Report whether the configured token (AHOOD_TOKEN or a stored login) still authenticates.",
+        inputSchema: {},
+    }, safeTool(async () => checkAuth()));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",
@@ -32,7 +32,9 @@
     "sync-readme": "node scripts/sync-readme.mjs"
   },
   "dependencies": {
-    "tar-stream": "^3.2.1"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "tar-stream": "^3.2.1",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/node": "^20",