@ikhono/mcp 0.2.1 → 0.2.6

package/README.md

@@ -132,6 +132,34 @@ Rate a skill after using it.
 | `stars` | number | Yes | Rating from 1 to 5 |
 | `review` | string | No | Optional text review |
 
+## Streamable HTTP Transport
+
+The iKhono MCP server is also available as a hosted HTTP endpoint, useful for MCP registries (Smithery, etc.) and web-based clients:
+
+```
+POST https://ikhono.io/mcp
+```
+
+Headers:
+- `Content-Type: application/json`
+- `Accept: application/json, text/event-stream`
+- `Authorization: Bearer YOUR_TOKEN` (optional, for authenticated operations)
+
+Sessions are stateful — the server returns an `Mcp-Session-Id` header to include in subsequent requests.
+
+### Programmatic Usage
+
+The server factory and client are available as package exports for embedding in your own server:
+
+```typescript
+import { createMcpServer } from '@ikhono/mcp/server';
+import { IkhonoClient } from '@ikhono/mcp/client';
+
+const client = new IkhonoClient({ apiUrl: 'https://ikhono.io', token: 'optional' });
+const server = createMcpServer(client);
+// Connect your own transport...
+```
+
 ## How It Works
 
 1. Your AI agent receives a task (e.g., "review this code")

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+interface IkhonoClientConfig {
+    apiUrl: string;
+    token?: string;
+}
+declare class IkhonoClient {
+    private apiUrl;
+    private token?;
+    constructor(config: IkhonoClientConfig);
+    private headers;
+    private handleResponse;
+    searchSkills(query: string, options?: {
+        category?: string;
+        author?: string;
+        mine?: boolean;
+        limit?: number;
+    }): Promise<unknown>;
+    getSkill(slug: string): Promise<unknown>;
+    pinSkill(slug: string): Promise<unknown>;
+    unpinSkill(slug: string): Promise<unknown>;
+    listPinned(): Promise<unknown>;
+    rateSkill(slug: string, stars: number, review?: string): Promise<unknown>;
+}
+
+export { IkhonoClient, type IkhonoClientConfig };

package/dist/client.js

@@ -0,0 +1,72 @@
+// src/client.ts
+var IkhonoClient = class {
+  apiUrl;
+  token;
+  constructor(config) {
+    this.apiUrl = config.apiUrl.replace(/\/$/, "");
+    this.token = config.token;
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.token) {
+      h["Authorization"] = `Bearer ${this.token}`;
+    }
+    return h;
+  }
+  async handleResponse(res, action) {
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const body = await res.json();
+        if (body.error) message = typeof body.error === "string" ? body.error : JSON.stringify(body.error);
+      } catch {
+      }
+      throw new Error(`${action}: ${message}`);
+    }
+    const json = await res.json();
+    return json.data;
+  }
+  async searchSkills(query, options) {
+    const params = new URLSearchParams();
+    if (query) params.set("q", query);
+    if (options?.category) params.set("category", options.category);
+    if (options?.author) params.set("author", options.author);
+    if (options?.mine) params.set("mine", "true");
+    if (options?.limit) params.set("limit", String(options.limit));
+    const res = await fetch(`${this.apiUrl}/api/skills?${params}`, { headers: this.headers() });
+    return this.handleResponse(res, "Search failed");
+  }
+  async getSkill(slug) {
+    const res = await fetch(`${this.apiUrl}/api/skills/${slug}?use=true`, { headers: this.headers() });
+    return this.handleResponse(res, "Get skill failed");
+  }
+  async pinSkill(slug) {
+    const res = await fetch(`${this.apiUrl}/api/skills/${slug}/pin`, {
+      method: "POST",
+      headers: this.headers()
+    });
+    return this.handleResponse(res, "Pin failed");
+  }
+  async unpinSkill(slug) {
+    const res = await fetch(`${this.apiUrl}/api/skills/${slug}/pin`, {
+      method: "DELETE",
+      headers: this.headers()
+    });
+    return this.handleResponse(res, "Unpin failed");
+  }
+  async listPinned() {
+    const res = await fetch(`${this.apiUrl}/api/skills/pinned`, { headers: this.headers() });
+    return this.handleResponse(res, "List pins failed");
+  }
+  async rateSkill(slug, stars, review) {
+    const res = await fetch(`${this.apiUrl}/api/skills/${slug}/rate`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ stars, review })
+    });
+    return this.handleResponse(res, "Rate failed");
+  }
+};
+export {
+  IkhonoClient
+};

package/dist/index.js

@@ -4,7 +4,6 @@
 import { readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/client.ts
@@ -77,6 +76,9 @@ var IkhonoClient = class {
   }
 };
 
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
 // src/tools/search.ts
 import { z } from "zod";
 var searchToolName = "ikhono_skill_search";
@@ -168,12 +170,101 @@ async function handleRate(client2, args2) {
 // src/version.ts
 import { createRequire } from "module";
 function getVersion() {
-  if (true) return "0.2.1";
+  if (true) return "0.2.6";
   const require2 = createRequire(import.meta.url);
   return require2("../package.json").version;
 }
 var VERSION = getVersion();
 
+// src/server.ts
+function createMcpServer(client2) {
+  const server2 = new McpServer({
+    name: "iKhono",
+    version: VERSION
+  }, {
+    instructions: `You have access to iKhono, a registry of AI skills that enhance your capabilities. When the user asks you to do something that could benefit from specialized expertise (code review, test writing, documentation, refactoring, etc.), use ikhono_skill_search to find relevant skills, then use ikhono_skill_get to load the skill's full instructions. Follow those instructions to give a better, more structured response. Always tell the user which skill you're using and its rating.`
+  });
+  server2.registerTool(searchToolName, {
+    description: searchToolDescription,
+    inputSchema: searchToolSchema.shape
+  }, async (args2) => {
+    try {
+      const results = await handleSearch(client2, searchToolSchema.parse(args2));
+      return { content: [{ type: "text", text: formatSearchResults(results) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server2.registerTool(getSkillToolName, {
+    description: getSkillToolDescription,
+    inputSchema: getSkillToolSchema.shape
+  }, async (args2) => {
+    try {
+      const parsed = getSkillToolSchema.parse(args2);
+      const skill = await handleGetSkill(client2, parsed);
+      const slug = parsed.slug;
+      const prompt = `IMPORTANT: After you finish the task using this skill, you MUST ask the user:
+"Would you like to pin or rate the skill ${slug}? Rate it 1-5 stars."
+If they respond with a rating, call ikhono_skill_rate with slug "${slug}" and their star count.
+If they want to pin it, call ikhono_skill_pin with slug "${slug}".
+This helps skill creators improve their work.`;
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(skill, null, 2) },
+          { type: "text", text: prompt }
+        ]
+      };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server2.registerTool(pinToolName, {
+    description: pinToolDescription,
+    inputSchema: pinToolSchema.shape
+  }, async (args2) => {
+    try {
+      const result = await handlePin(client2, pinToolSchema.parse(args2));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server2.registerTool(unpinToolName, {
+    description: unpinToolDescription,
+    inputSchema: unpinToolSchema.shape
+  }, async (args2) => {
+    try {
+      const result = await handleUnpin(client2, unpinToolSchema.parse(args2));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server2.registerTool(listPinnedToolName, {
+    description: listPinnedToolDescription,
+    inputSchema: listPinnedToolSchema.shape
+  }, async () => {
+    try {
+      const result = await handleListPinned(client2);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server2.registerTool(rateToolName, {
+    description: rateToolDescription,
+    inputSchema: rateToolSchema.shape
+  }, async (args2) => {
+    try {
+      const result = await handleRate(client2, rateToolSchema.parse(args2));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  return server2;
+}
+
 // src/index.ts
 function readCliConfig() {
   try {
@@ -199,89 +290,6 @@ for (let i = 0; i < args.length; i++) {
 apiUrl = process.env.IKHONO_API_URL || apiUrl || cliConfig.apiUrl || "https://ikhono.io";
 token = process.env.IKHONO_API_TOKEN || token || cliConfig.token;
 var client = new IkhonoClient({ apiUrl, token });
-var server = new McpServer({
-  name: "iKhono",
-  version: VERSION
-}, {
-  instructions: `You have access to iKhono, a registry of AI skills that enhance your capabilities. When the user asks you to do something that could benefit from specialized expertise (code review, test writing, documentation, refactoring, etc.), use ikhono_skill_search to find relevant skills, then use ikhono_skill_get to load the skill's full instructions. Follow those instructions to give a better, more structured response. Always tell the user which skill you're using and its rating.`
-});
-server.registerTool(searchToolName, {
-  description: searchToolDescription,
-  inputSchema: searchToolSchema.shape
-}, async (args2) => {
-  try {
-    const results = await handleSearch(client, searchToolSchema.parse(args2));
-    return { content: [{ type: "text", text: formatSearchResults(results) }] };
-  } catch (err) {
-    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-  }
-});
-server.registerTool(getSkillToolName, {
-  description: getSkillToolDescription,
-  inputSchema: getSkillToolSchema.shape
-}, async (args2) => {
-  try {
-    const parsed = getSkillToolSchema.parse(args2);
-    const skill = await handleGetSkill(client, parsed);
-    const slug = parsed.slug;
-    const prompt = `IMPORTANT: After you finish the task using this skill, you MUST ask the user:
-"Would you like to pin or rate the skill ${slug}? Rate it 1-5 stars."
-If they respond with a rating, call ikhono_skill_rate with slug "${slug}" and their star count.
-If they want to pin it, call ikhono_skill_pin with slug "${slug}".
-This helps skill creators improve their work.`;
-    return {
-      content: [
-        { type: "text", text: JSON.stringify(skill, null, 2) },
-        { type: "text", text: prompt }
-      ]
-    };
-  } catch (err) {
-    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-  }
-});
-server.registerTool(pinToolName, {
-  description: pinToolDescription,
-  inputSchema: pinToolSchema.shape
-}, async (args2) => {
-  try {
-    const result = await handlePin(client, pinToolSchema.parse(args2));
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  } catch (err) {
-    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-  }
-});
-server.registerTool(unpinToolName, {
-  description: unpinToolDescription,
-  inputSchema: unpinToolSchema.shape
-}, async (args2) => {
-  try {
-    const result = await handleUnpin(client, unpinToolSchema.parse(args2));
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  } catch (err) {
-    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-  }
-});
-server.registerTool(listPinnedToolName, {
-  description: listPinnedToolDescription,
-  inputSchema: listPinnedToolSchema.shape
-}, async () => {
-  try {
-    const result = await handleListPinned(client);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  } catch (err) {
-    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-  }
-});
-server.registerTool(rateToolName, {
-  description: rateToolDescription,
-  inputSchema: rateToolSchema.shape
-}, async (args2) => {
-  try {
-    const result = await handleRate(client, rateToolSchema.parse(args2));
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  } catch (err) {
-    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-  }
-});
+var server = createMcpServer(client);
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { IkhonoClient } from './client.js';
+
+declare function createMcpServer(client: IkhonoClient): McpServer;
+
+export { createMcpServer };

package/dist/server.js

@@ -0,0 +1,191 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/search.ts
+import { z } from "zod";
+var searchToolName = "ikhono_skill_search";
+var searchToolSchema = z.object({
+  query: z.string().optional().default("").describe('Search query to find relevant skills (e.g., "security review", "write tests", "api docs"). Leave empty when using mine or author filters to list all matching skills.'),
+  category: z.string().optional().describe('Filter by category (e.g., "security", "testing", "documentation")'),
+  author: z.string().optional().describe('Filter by author username (e.g., "@alice" or "alice")'),
+  mine: z.boolean().optional().describe("Set to true to show only your own skills (requires authentication)"),
+  limit: z.number().optional().default(3).describe("Maximum number of results to return")
+});
+var searchToolDescription = `Search iKhono for AI skills that match a query. Use this when the user asks you to do something that could benefit from specialized expertise. Returns a list of matching skills with their names, descriptions, ratings, usage counts, and pin counts.`;
+function formatSearchResults(results) {
+  if (results.length === 0) {
+    return "No skills found matching your query.";
+  }
+  const lines = [`Found ${results.length} skill${results.length === 1 ? "" : "s"}:
+`];
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    const rating = r.avgRating > 0 ? `${r.avgRating.toFixed(1)}/5 (${r.ratingCount} rating${r.ratingCount === 1 ? "" : "s"})` : "no ratings yet";
+    lines.push(`${i + 1}. ${r.slug} (v${r.latestVersion})`);
+    lines.push(`   ${r.description}`);
+    lines.push(`   ${rating} \xB7 ${r.totalUses} uses \xB7 ${r.pinCount} pins`);
+    lines.push("");
+  }
+  lines.push("Load a skill with ikhono_skill_get using the slug.");
+  return lines.join("\n");
+}
+async function handleSearch(client, args) {
+  const results = await client.searchSkills(args.query, {
+    category: args.category,
+    author: args.author,
+    mine: args.mine,
+    limit: args.limit
+  });
+  return results;
+}
+
+// src/tools/get-skill.ts
+import { z as z2 } from "zod";
+var getSkillToolName = "ikhono_skill_get";
+var getSkillToolSchema = z2.object({
+  slug: z2.string().describe('The skill slug (e.g., "@alice/security-reviewer"). Get this from ikhono_skill_search results.')
+});
+var getSkillToolDescription = `Load a skill from iKhono by its slug. Returns the full skill content (instructions, process, templates) that you should follow to complete the user's task. After searching with ikhono_skill_search, use this tool to load the best matching skill.`;
+async function handleGetSkill(client, args) {
+  const skill = await client.getSkill(args.slug);
+  return skill;
+}
+
+// src/tools/pin.ts
+import { z as z3 } from "zod";
+var pinToolName = "ikhono_skill_pin";
+var pinToolSchema = z3.object({
+  slug: z3.string().describe('The skill slug to pin (e.g., "@alice/security-reviewer")')
+});
+var pinToolDescription = `Pin a skill to the user's favorites so it's always available. Pinned skills are shown in the user's profile.`;
+async function handlePin(client, args) {
+  return await client.pinSkill(args.slug);
+}
+var unpinToolName = "ikhono_skill_unpin";
+var unpinToolSchema = z3.object({
+  slug: z3.string().describe("The skill slug to unpin")
+});
+var unpinToolDescription = `Remove a skill from the user's pinned favorites.`;
+async function handleUnpin(client, args) {
+  return await client.unpinSkill(args.slug);
+}
+var listPinnedToolName = "ikhono_skill_list_pinned";
+var listPinnedToolSchema = z3.object({});
+var listPinnedToolDescription = `List all skills the user has pinned. Returns pinned skills with their names, descriptions, and ratings.`;
+async function handleListPinned(client) {
+  return await client.listPinned();
+}
+
+// src/tools/rate.ts
+import { z as z4 } from "zod";
+var rateToolName = "ikhono_skill_rate";
+var rateToolSchema = z4.object({
+  slug: z4.string().describe('The skill slug to rate (e.g., "@alice/security-reviewer")'),
+  stars: z4.number().min(1).max(5).describe("Rating from 1 to 5 stars"),
+  review: z4.string().optional().describe("Optional text review")
+});
+var rateToolDescription = `Rate a skill after using it. Helps the community discover the best skills.`;
+async function handleRate(client, args) {
+  return await client.rateSkill(args.slug, args.stars, args.review);
+}
+
+// src/version.ts
+import { createRequire } from "module";
+function getVersion() {
+  if (true) return "0.2.6";
+  const require2 = createRequire(import.meta.url);
+  return require2("../package.json").version;
+}
+var VERSION = getVersion();
+
+// src/server.ts
+function createMcpServer(client) {
+  const server = new McpServer({
+    name: "iKhono",
+    version: VERSION
+  }, {
+    instructions: `You have access to iKhono, a registry of AI skills that enhance your capabilities. When the user asks you to do something that could benefit from specialized expertise (code review, test writing, documentation, refactoring, etc.), use ikhono_skill_search to find relevant skills, then use ikhono_skill_get to load the skill's full instructions. Follow those instructions to give a better, more structured response. Always tell the user which skill you're using and its rating.`
+  });
+  server.registerTool(searchToolName, {
+    description: searchToolDescription,
+    inputSchema: searchToolSchema.shape
+  }, async (args) => {
+    try {
+      const results = await handleSearch(client, searchToolSchema.parse(args));
+      return { content: [{ type: "text", text: formatSearchResults(results) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool(getSkillToolName, {
+    description: getSkillToolDescription,
+    inputSchema: getSkillToolSchema.shape
+  }, async (args) => {
+    try {
+      const parsed = getSkillToolSchema.parse(args);
+      const skill = await handleGetSkill(client, parsed);
+      const slug = parsed.slug;
+      const prompt = `IMPORTANT: After you finish the task using this skill, you MUST ask the user:
+"Would you like to pin or rate the skill ${slug}? Rate it 1-5 stars."
+If they respond with a rating, call ikhono_skill_rate with slug "${slug}" and their star count.
+If they want to pin it, call ikhono_skill_pin with slug "${slug}".
+This helps skill creators improve their work.`;
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(skill, null, 2) },
+          { type: "text", text: prompt }
+        ]
+      };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool(pinToolName, {
+    description: pinToolDescription,
+    inputSchema: pinToolSchema.shape
+  }, async (args) => {
+    try {
+      const result = await handlePin(client, pinToolSchema.parse(args));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool(unpinToolName, {
+    description: unpinToolDescription,
+    inputSchema: unpinToolSchema.shape
+  }, async (args) => {
+    try {
+      const result = await handleUnpin(client, unpinToolSchema.parse(args));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool(listPinnedToolName, {
+    description: listPinnedToolDescription,
+    inputSchema: listPinnedToolSchema.shape
+  }, async () => {
+    try {
+      const result = await handleListPinned(client);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool(rateToolName, {
+    description: rateToolDescription,
+    inputSchema: rateToolSchema.shape
+  }, async (args) => {
+    try {
+      const result = await handleRate(client, rateToolSchema.parse(args));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  return server;
+}
+export {
+  createMcpServer
+};

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "@ikhono/mcp",
-  "version": "0.2.1",
+  "version": "0.2.6",
   "description": "iKhono MCP Server — runtime skill router for AI agents",
   "type": "module",
   "bin": {
     "ikhono-mcp": "./dist/index.js"
   },
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
   "files": [
     "dist"
   ],