superkit-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# Super-Kit MCP Server
+
+This is a Model Context Protocol (MCP) server that exposes the agents, skills, and workflows of **Super-Kit** to any compatible AI assistant (Cline, Cursor, Gemini, etc.).
+
+By installing this MCP server, your AI agent can dynamically list, read, and load the specific operational contexts it needs on the fly, without needing massive system prompts.
+
+## Available Tools
+
+- **`list_superkit_assets`**: Lists all available agents, skills (tech/meta), and workflows in the Super-Kit repository.
+- **`load_superkit_agent`**: Loads the system instructions and guidelines for a specific specialist agent (e.g., `data-engineer`).
+- **`load_superkit_skill`**: Loads the skill instructions (`SKILL.md`) for a specific category and skill (e.g., category: `tech`, name: `react-best-practices`).
+- **`load_superkit_workflow`**: Loads the instructions for a specific slash-command workflow (e.g., `work`, `explore`).
+
+## Installation
+
+```bash
+cd super-kit/mcp-server
+npm install
+npm run build
+```
+
+## Configuring in AI Platforms
+
+### Cline (VS Code)
+Add the following to your `cline_mcp_settings.json`:
+```json
+{
+  "mcpServers": {
+    "superkit": {
+      "command": "node",
+      "args": ["/absolute/path/to/super-kit/mcp-server/build/index.js"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+Go to Settings -> Features -> MCP Servers.
+Add a new stdio server:
+- Name: `superkit`
+- Command: `node /absolute/path/to/super-kit/mcp-server/build/index.js`
+
+## How it works
+The server reads directly from the parent `super-kit` directory, resolving paths safely to prevent traversal attacks. It automatically parses and returns the Markdown contents of the structural elements.

package/build/index.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import * as path from "path";
+import * as fs from "fs/promises";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Assuming __dirname is super-kit/mcp-server/build
+const IS_BUILD = __dirname.endsWith("build");
+const superKitRoot = IS_BUILD ? path.resolve(__dirname, "../../") : path.resolve(__dirname, "../");
+const server = new Server({
+    name: "superkit-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Helper function to read directory contents, tracking if they are directories or files
+async function listDirectorySafe(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        return entries.map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name));
+    }
+    catch (err) {
+        return [];
+    }
+}
+// Ensure safe path resolution to prevent traversal
+function getSafePath(basePath, relativePath) {
+    // Normalize and resolve
+    const resolvedPath = path.resolve(basePath, relativePath);
+    // Check if it starts with the basePath
+    if (!resolvedPath.startsWith(basePath)) {
+        return null; // Path traversal detected
+    }
+    return resolvedPath;
+}
+const TOOLS = [
+    {
+        name: "list_superkit_assets",
+        description: "Lists all available agents, skills, and workflows in the Super-Kit repository.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "load_superkit_agent",
+        description: "Loads the instruction markdown for a specific specialist agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agentName: {
+                    type: "string",
+                    description: "The name of the agent to load (e.g., 'data-engineer'). Do not include .md.",
+                },
+            },
+            required: ["agentName"],
+        },
+    },
+    {
+        name: "load_superkit_skill",
+        description: "Loads the skill index (SKILL.md) or specific reference file for a skill.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "The category of the skill (e.g., 'tech', 'meta', 'workflows').",
+                },
+                skillName: {
+                    type: "string",
+                    description: "The name of the skill directory (e.g., 'react-best-practices').",
+                },
+            },
+            required: ["category", "skillName"],
+        },
+    },
+    {
+        name: "load_superkit_workflow",
+        description: "Loads the instructions for a specific workflow.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workflowName: {
+                    type: "string",
+                    description: "The name of the workflow (e.g., 'plan', 'explore'). Do not include .md.",
+                },
+            },
+            required: ["workflowName"],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        if (request.params.name === "list_superkit_assets") {
+            const agentsPath = path.join(superKitRoot, "agents");
+            const skillsTechPath = path.join(superKitRoot, "skills", "tech");
+            const skillsMetaPath = path.join(superKitRoot, "skills", "meta");
+            const workflowsPath = path.join(superKitRoot, "workflows");
+            const agents = await listDirectorySafe(agentsPath);
+            const techSkills = await listDirectorySafe(skillsTechPath);
+            const metaSkills = await listDirectorySafe(skillsMetaPath);
+            const workflows = await listDirectorySafe(workflowsPath);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            agents: agents.map((a) => a.replace(".md", "")),
+                            skills: {
+                                tech: techSkills.map((s) => s.replace("/", "")),
+                                meta: metaSkills.map((s) => s.replace("/", "")),
+                            },
+                            workflows: workflows.map((w) => w.replace(".md", "")),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (request.params.name === "load_superkit_agent") {
+            const args = request.params.arguments;
+            if (!args.agentName)
+                throw new Error("Missing agentName");
+            const agentFile = `${args.agentName}.md`;
+            const baseDir = path.join(superKitRoot, "agents");
+            const safePath = getSafePath(baseDir, agentFile);
+            if (!safePath)
+                throw new Error("Invalid agent path");
+            const content = await fs.readFile(safePath, "utf-8");
+            return { content: [{ type: "text", text: content }] };
+        }
+        if (request.params.name === "load_superkit_skill") {
+            const args = request.params.arguments;
+            if (!args.category || !args.skillName)
+                throw new Error("Missing category or skillName");
+            const baseDir = path.join(superKitRoot, "skills", args.category, args.skillName);
+            const safePath = getSafePath(path.join(superKitRoot, "skills"), path.join(args.category, args.skillName, "SKILL.md"));
+            if (!safePath)
+                throw new Error("Invalid skill path");
+            try {
+                const content = await fs.readFile(safePath, "utf-8");
+                return { content: [{ type: "text", text: content }] };
+            }
+            catch (e) {
+                // If SKILL.md isn't there, just return the directory context if we can.
+                const fallbackSafePath = getSafePath(path.join(superKitRoot, "skills"), path.join(args.category, args.skillName));
+                if (fallbackSafePath) {
+                    const items = await listDirectorySafe(fallbackSafePath);
+                    return { content: [{ type: "text", text: `SKILL.md not found. Directory contains: ${items.join(', ')}` }] };
+                }
+                throw e;
+            }
+        }
+        if (request.params.name === "load_superkit_workflow") {
+            const args = request.params.arguments;
+            if (!args.workflowName)
+                throw new Error("Missing workflowName");
+            const workflowFile = `${args.workflowName}.md`;
+            const baseDir = path.join(superKitRoot, "workflows");
+            const safePath = getSafePath(baseDir, workflowFile);
+            if (!safePath)
+                throw new Error("Invalid workflow path");
+            const content = await fs.readFile(safePath, "utf-8");
+            return { content: [{ type: "text", text: content }] };
+        }
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error executing tool: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Super-Kit MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "superkit-mcp-server",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "An MCP server for exploring and loading Super-Kit AI agent resources.",
+    "main": "build/index.js",
+    "bin": {
+        "superkit-mcp-server": "./build/index.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "start": "node build/index.js",
+        "dev": "tsc --watch"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.4.1",
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.1",
+        "typescript": "^5.7.2"
+    }
+}

package/src/index.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+    Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import * as path from "path";
+import * as fs from "fs/promises";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Assuming __dirname is super-kit/mcp-server/build
+const IS_BUILD = __dirname.endsWith("build");
+const superKitRoot = IS_BUILD ? path.resolve(__dirname, "../../") : path.resolve(__dirname, "../");
+
+const server = new Server(
+    {
+        name: "superkit-mcp-server",
+        version: "1.0.0",
+    },
+    {
+        capabilities: {
+            tools: {},
+        },
+    }
+);
+
+// Helper function to read directory contents, tracking if they are directories or files
+async function listDirectorySafe(dirPath: string): Promise<string[]> {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        return entries.map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name));
+    } catch (err) {
+        return [];
+    }
+}
+
+// Ensure safe path resolution to prevent traversal
+function getSafePath(basePath: string, relativePath: string): string | null {
+    // Normalize and resolve
+    const resolvedPath = path.resolve(basePath, relativePath);
+    // Check if it starts with the basePath
+    if (!resolvedPath.startsWith(basePath)) {
+        return null; // Path traversal detected
+    }
+    return resolvedPath;
+}
+
+const TOOLS: Tool[] = [
+    {
+        name: "list_superkit_assets",
+        description: "Lists all available agents, skills, and workflows in the Super-Kit repository.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "load_superkit_agent",
+        description: "Loads the instruction markdown for a specific specialist agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agentName: {
+                    type: "string",
+                    description: "The name of the agent to load (e.g., 'data-engineer'). Do not include .md.",
+                },
+            },
+            required: ["agentName"],
+        },
+    },
+    {
+        name: "load_superkit_skill",
+        description: "Loads the skill index (SKILL.md) or specific reference file for a skill.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "The category of the skill (e.g., 'tech', 'meta', 'workflows').",
+                },
+                skillName: {
+                    type: "string",
+                    description: "The name of the skill directory (e.g., 'react-best-practices').",
+                },
+            },
+            required: ["category", "skillName"],
+        },
+    },
+    {
+        name: "load_superkit_workflow",
+        description: "Loads the instructions for a specific workflow.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workflowName: {
+                    type: "string",
+                    description: "The name of the workflow (e.g., 'plan', 'explore'). Do not include .md.",
+                },
+            },
+            required: ["workflowName"],
+        },
+    },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        if (request.params.name === "list_superkit_assets") {
+            const agentsPath = path.join(superKitRoot, "agents");
+            const skillsTechPath = path.join(superKitRoot, "skills", "tech");
+            const skillsMetaPath = path.join(superKitRoot, "skills", "meta");
+            const workflowsPath = path.join(superKitRoot, "workflows");
+
+            const agents = await listDirectorySafe(agentsPath);
+            const techSkills = await listDirectorySafe(skillsTechPath);
+            const metaSkills = await listDirectorySafe(skillsMetaPath);
+            const workflows = await listDirectorySafe(workflowsPath);
+
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(
+                            {
+                                agents: agents.map((a) => a.replace(".md", "")),
+                                skills: {
+                                    tech: techSkills.map((s) => s.replace("/", "")),
+                                    meta: metaSkills.map((s) => s.replace("/", "")),
+                                },
+                                workflows: workflows.map((w) => w.replace(".md", "")),
+                            },
+                            null,
+                            2
+                        ),
+                    },
+                ],
+            };
+        }
+
+        if (request.params.name === "load_superkit_agent") {
+            const args = request.params.arguments as { agentName: string };
+            if (!args.agentName) throw new Error("Missing agentName");
+
+            const agentFile = `${args.agentName}.md`;
+            const baseDir = path.join(superKitRoot, "agents");
+            const safePath = getSafePath(baseDir, agentFile);
+
+            if (!safePath) throw new Error("Invalid agent path");
+
+            const content = await fs.readFile(safePath, "utf-8");
+            return { content: [{ type: "text", text: content }] };
+        }
+
+        if (request.params.name === "load_superkit_skill") {
+            const args = request.params.arguments as { category: string; skillName: string };
+            if (!args.category || !args.skillName) throw new Error("Missing category or skillName");
+
+            const baseDir = path.join(superKitRoot, "skills", args.category, args.skillName);
+            const safePath = getSafePath(path.join(superKitRoot, "skills"), path.join(args.category, args.skillName, "SKILL.md"));
+
+            if (!safePath) throw new Error("Invalid skill path");
+
+            try {
+                const content = await fs.readFile(safePath, "utf-8");
+                return { content: [{ type: "text", text: content }] };
+            } catch (e) {
+                // If SKILL.md isn't there, just return the directory context if we can.
+                const fallbackSafePath = getSafePath(path.join(superKitRoot, "skills"), path.join(args.category, args.skillName));
+                if (fallbackSafePath) {
+                    const items = await listDirectorySafe(fallbackSafePath);
+                    return { content: [{ type: "text", text: `SKILL.md not found. Directory contains: ${items.join(', ')}` }] };
+                }
+                throw e;
+            }
+        }
+
+        if (request.params.name === "load_superkit_workflow") {
+            const args = request.params.arguments as { workflowName: string };
+            if (!args.workflowName) throw new Error("Missing workflowName");
+
+            const workflowFile = `${args.workflowName}.md`;
+            const baseDir = path.join(superKitRoot, "workflows");
+            const safePath = getSafePath(baseDir, workflowFile);
+
+            if (!safePath) throw new Error("Invalid workflow path");
+
+            const content = await fs.readFile(safePath, "utf-8");
+            return { content: [{ type: "text", text: content }] };
+        }
+
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    } catch (error: any) {
+        return {
+            content: [{ type: "text", text: `Error executing tool: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Super-Kit MCP Server running on stdio");
+}
+
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "outDir": "./build",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src/**/*"
+    ]
+}