@ikhono/mcp 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,155 @@
+# @ikhono/mcp
+
+MCP server for [iKhono](https://github.com/ikhono/ikhono) — a runtime skill router that gives AI agents access to community-built skills on the fly.
+
+No local skill installation needed. Your AI agent searches, loads, and follows skills directly from the iKhono registry.
+
+## Quick Setup
+
+### Claude Code
+
+```bash
+claude mcp add ikhono -- npx -y @ikhono/mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ikhono": {
+      "command": "npx",
+      "args": ["-y", "@ikhono/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ikhono": {
+      "command": "npx",
+      "args": ["-y", "@ikhono/mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ikhono": {
+      "command": "npx",
+      "args": ["-y", "@ikhono/mcp"]
+    }
+  }
+}
+```
+
+## Authentication
+
+To use authenticated features (pinning, rating, publishing your own skills), log in with the CLI first:
+
+```bash
+npx @ikhono/cli login --email you@example.com --password yourpass
+```
+
+The MCP server automatically reads your token from `~/.ikhono/config.json`.
+
+You can also pass credentials directly:
+
+```bash
+# Via CLI args
+npx @ikhono/mcp --token YOUR_TOKEN --api-url https://api.ikhono.io
+
+# Via environment variables
+IKHONO_API_TOKEN=YOUR_TOKEN npx @ikhono/mcp
+```
+
+**Priority order:** environment variables > CLI args > `~/.ikhono/config.json`
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `ikhono_skill_search` | Search for skills by query, category, or author (returns top 3 previews) |
+| `ikhono_skill_get` | Load a skill's full instructions by slug |
+| `ikhono_skill_pin` | Pin a skill to your favorites |
+| `ikhono_skill_unpin` | Remove a skill from your favorites |
+| `ikhono_skill_list_pinned` | List your pinned skills |
+| `ikhono_skill_rate` | Rate a skill (1-5 stars) |
+
+### ikhono_skill_search
+
+Search for skills matching a query. Returns a concise preview of the top results (default: 3) with name, description, rating, and usage stats. Use `ikhono_skill_get` to load the full skill instructions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | No | Search text (e.g., "code review", "test writing") |
+| `category` | string | No | Filter by category |
+| `author` | string | No | Filter by author (e.g., "@alice") |
+| `mine` | boolean | No | Show only your skills |
+| `limit` | number | No | Max results (default: 3) |
+
+### ikhono_skill_get
+
+Load a skill's full content to follow its instructions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `slug` | string | Yes | Skill slug (e.g., "@alice/code-reviewer") |
+
+### ikhono_skill_pin / ikhono_skill_unpin
+
+Pin or unpin a skill.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `slug` | string | Yes | Skill slug to pin/unpin |
+
+### ikhono_skill_list_pinned
+
+List all pinned skills. No parameters.
+
+### ikhono_skill_rate
+
+Rate a skill after using it.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `slug` | string | Yes | Skill slug to rate |
+| `stars` | number | Yes | Rating from 1 to 5 |
+| `review` | string | No | Optional text review |
+
+## How It Works
+
+1. Your AI agent receives a task (e.g., "review this code")
+2. The agent calls `ikhono_skill_search` to find relevant skills (top 3 previews)
+3. The user picks which skill to load — the agent calls `ikhono_skill_get` with that slug
+4. The agent follows the skill's instructions for a better, more structured response
+
+If none of the results fit, the user can ask to search again with a higher `limit` or a different query.
+
+Skills are community-created Markdown documents with structured processes, checklists, and templates. The MCP server is a thin proxy to the iKhono API — no local storage or computation needed.
+
+## Links
+
+- [Getting Started](https://github.com/ikhono/ikhono/blob/main/docs/getting-started.md)
+- [Creating Skills](https://github.com/ikhono/ikhono/blob/main/docs/creating-skills.md)
+- [CLI Reference](https://github.com/ikhono/ikhono/blob/main/docs/cli-reference.md)
+- [GitHub](https://github.com/ikhono/ikhono)
+
+## License
+
+MIT

package/dist/index.js

@@ -85,9 +85,26 @@ var searchToolSchema = z.object({
   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(5).describe("Maximum number of results to return")
+  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(client2, args2) {
   const results = await client2.searchSkills(args2.query, {
     category: args2.category,
@@ -151,7 +168,7 @@ async function handleRate(client2, args2) {
 // src/version.ts
 import { createRequire } from "module";
 function getVersion() {
-  if (true) return "0.1.0";
+  if (true) return "0.1.3";
   const require2 = createRequire(import.meta.url);
   return require2("../package.json").version;
 }
@@ -191,7 +208,7 @@ var server = new McpServer({
 server.tool(searchToolName, searchToolDescription, searchToolSchema.shape, async (args2) => {
   try {
     const results = await handleSearch(client, searchToolSchema.parse(args2));
-    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    return { content: [{ type: "text", text: formatSearchResults(results) }] };
   } catch (err) {
     return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikhono/mcp",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "iKhono MCP Server — runtime skill router for AI agents",
   "type": "module",
   "bin": {
@@ -9,12 +9,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsx watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0"
@@ -27,5 +21,11 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}