modelbound-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ModelBound
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# modelbound-mcp
+
+> Local-first MCP server for agent skills. Validate, lint, diff, and convert agent skill files across Cursor, Claude, Kiro, Windsurf, VS Code, and Amazon Q — no account required. Optional cloud sync with [ModelBound](https://modelbound.co).
+
+[![npm](https://img.shields.io/npm/v/modelbound-mcp.svg)](https://www.npmjs.com/package/modelbound-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## What it does
+
+`modelbound-mcp` is a small [Model Context Protocol](https://modelcontextprotocol.io) server you run locally over stdio. It exposes tools to your IDE / agent:
+
+**Local (no API key, no network):**
+- `detect_ide_layout` — find which IDE conventions your repo uses
+- `list_local_skills`, `read_local_skill`, `write_local_skill`
+- `lint_skill` — front-matter, token count, broken links, TODO scan
+- `validate_skill_format` — agentskills.io compliance
+- `convert_skill` — translate between IDE formats (e.g. Cursor → Claude)
+
+**Cloud (with `MODELBOUND_API_KEY`):**
+- `pull_skill`, `push_skill`, `list_cloud_skills`, `search_cloud`, `diff_skill`
+- `install_marketplace_skill`, `get_context_health`
+
+The cloud tools are a thin JSON-RPC proxy to `mcp.modelbound.co`. All business logic stays server-side; this repo never touches your data or secrets.
+
+## Install
+
+No install needed:
+
+```bash
+npx modelbound-mcp
+```
+
+Or install globally:
+
+```bash
+npm i -g modelbound-mcp
+```
+
+## Use as an MCP server
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "modelbound": {
+      "command": "npx",
+      "args": ["-y", "modelbound-mcp"],
+      "env": { "MODELBOUND_API_KEY": "mb_live_..." }
+    }
+  }
+}
+```
+
+`MODELBOUND_API_KEY` is optional. Without it, local tools still work.
+
+See [`examples/`](./examples) for Claude Desktop, Kiro, Windsurf, and VS Code configs.
+
+## Use as a CLI
+
+```bash
+modelbound-mcp detect                                  # which IDE layouts exist here?
+modelbound-mcp ls                                      # list every skill file
+modelbound-mcp lint .cursor/rules/                     # lint a directory
+modelbound-mcp validate ./SKILL.md                     # agentskills.io compliance
+modelbound-mcp convert --from cursor --to claude ./rule.mdc > out.md
+```
+
+## Contributing
+
+We want help. Specifically:
+
+- **New IDE adapters** — Zed, Aider, Continue, JetBrains AI, Cline. See [CONTRIBUTING.md](CONTRIBUTING.md) for the ~50 line recipe.
+- **Linter rules** — token estimation accuracy, dead-link detection, format-specific gotchas.
+- **Format converters** — fidelity improvements between adapter pairs.
+
+Browse [good first issues](https://github.com/ModelBound/modelbound-mcp-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and the [roadmap](ROADMAP.md).
+
+## License
+
+MIT © ModelBound

package/dist/adapters/index.d.ts

@@ -0,0 +1,13 @@
+import type { IdeAdapter } from "./types.js";
+export { listAdapterFiles } from "./types.js";
+export type { IdeAdapter, CanonicalSkill } from "./types.js";
+export declare const cursor: IdeAdapter;
+export declare const claude: IdeAdapter;
+export declare const kiro: IdeAdapter;
+export declare const windsurf: IdeAdapter;
+export declare const vscode: IdeAdapter;
+export declare const amazonQ: IdeAdapter;
+export declare const agentsMd: IdeAdapter;
+export declare const ALL_ADAPTERS: IdeAdapter[];
+export declare function getAdapter(id: string): IdeAdapter | undefined;
+export declare function detectAdapters(cwd: string): IdeAdapter[];

package/dist/adapters/index.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+export { listAdapterFiles } from "./types.js";
+const mdAdapter = (id, name, skillsDir, fileExt = ".md", detect) => ({
+    id,
+    name,
+    skillsDir,
+    fileExt,
+    detect: detect ?? ((cwd) => fs.existsSync(path.join(cwd, skillsDir))),
+    toCanonical: (raw) => {
+        const parsed = matter(raw);
+        return { frontmatter: parsed.data ?? {}, body: parsed.content.trim() };
+    },
+    fromCanonical: ({ frontmatter, body }) => Object.keys(frontmatter).length
+        ? matter.stringify(body, frontmatter)
+        : body + "\n",
+});
+export const cursor = mdAdapter("cursor", "Cursor", ".cursor/rules", ".mdc", (cwd) => fs.existsSync(path.join(cwd, ".cursor")));
+export const claude = mdAdapter("claude", "Claude Code", ".claude/skills", ".md", (cwd) => fs.existsSync(path.join(cwd, ".claude")));
+export const kiro = mdAdapter("kiro", "Kiro", ".kiro/skills", ".md", (cwd) => fs.existsSync(path.join(cwd, ".kiro")));
+export const windsurf = mdAdapter("windsurf", "Windsurf", ".windsurf/rules", ".md", (cwd) => fs.existsSync(path.join(cwd, ".windsurf")));
+export const vscode = mdAdapter("vscode-copilot", "VS Code / GitHub Copilot", ".github/copilot", ".md", (cwd) => fs.existsSync(path.join(cwd, ".github/copilot")));
+export const amazonQ = mdAdapter("amazon-q", "Amazon Q", ".amazonq/rules", ".md", (cwd) => fs.existsSync(path.join(cwd, ".amazonq")));
+export const agentsMd = mdAdapter("agents-md", "AGENTS.md (generic)", ".", ".md", (cwd) => fs.existsSync(path.join(cwd, "AGENTS.md")));
+export const ALL_ADAPTERS = [
+    cursor,
+    claude,
+    kiro,
+    windsurf,
+    vscode,
+    amazonQ,
+    agentsMd,
+];
+export function getAdapter(id) {
+    return ALL_ADAPTERS.find((a) => a.id === id);
+}
+export function detectAdapters(cwd) {
+    return ALL_ADAPTERS.filter((a) => a.detect(cwd));
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * IDE adapter interface. Each adapter knows where a given IDE stores its
+ * agent skill / rules files and how to translate that IDE's flavor of a
+ * skill file to and from a canonical { frontmatter, body } representation.
+ *
+ * Adding a new IDE is the single best way to contribute to this project.
+ * See CONTRIBUTING.md for a 10-line recipe.
+ */
+export interface CanonicalSkill {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export interface IdeAdapter {
+    /** Stable identifier used in CLI args, e.g. `cursor`, `claude`. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Returns true if this IDE's project marker exists in `cwd`. */
+    detect: (cwd: string) => boolean;
+    /** Project-relative directory that holds skill / rule files. */
+    skillsDir: string;
+    /** File extension this IDE uses for its skill files (e.g. `.mdc`, `.md`). */
+    fileExt: string;
+    /** Parse a raw file body into the canonical representation. */
+    toCanonical: (raw: string) => CanonicalSkill;
+    /** Serialize the canonical representation back to this IDE's format. */
+    fromCanonical: (skill: CanonicalSkill) => string;
+}
+/** Walk the skills directory and return absolute file paths. */
+export declare function listAdapterFiles(adapter: IdeAdapter, cwd: string): string[];

package/dist/adapters/types.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+/** Walk the skills directory and return absolute file paths. */
+export function listAdapterFiles(adapter, cwd) {
+    const dir = path.join(cwd, adapter.skillsDir);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    const walk = (d) => {
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+            const full = path.join(d, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile() && full.endsWith(adapter.fileExt))
+                out.push(full);
+        }
+    };
+    walk(dir);
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Standalone CLI: `modelbound-mcp <subcommand>`
+ *
+ * Without arguments, launches the MCP stdio server (this is what IDEs invoke).
+ * With a subcommand, runs that subcommand against the filesystem.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ALL_ADAPTERS, detectAdapters, getAdapter, listAdapterFiles } from "./adapters/index.js";
+import { lintSkill, validateAgentSkillsFormat } from "./lib/lint.js";
+const args = process.argv.slice(2);
+const cmd = args[0];
+if (!cmd) {
+    // No subcommand → boot the MCP server.
+    await import("./index.js");
+}
+else if (cmd === "validate") {
+    const file = args[1];
+    if (!file)
+        die("Usage: modelbound-mcp validate <file>");
+    const report = validateAgentSkillsFormat(fs.readFileSync(file, "utf8"));
+    printReport(file, report);
+    process.exit(report.ok ? 0 : 1);
+}
+else if (cmd === "lint") {
+    const target = args[1] ?? ".";
+    const stat = fs.statSync(target);
+    let failed = false;
+    const files = stat.isDirectory()
+        ? walk(target).filter((f) => f.endsWith(".md") || f.endsWith(".mdc"))
+        : [target];
+    for (const f of files) {
+        const report = lintSkill(fs.readFileSync(f, "utf8"));
+        printReport(f, report);
+        if (!report.ok)
+            failed = true;
+    }
+    process.exit(failed ? 1 : 0);
+}
+else if (cmd === "convert") {
+    const fromIdx = args.indexOf("--from");
+    const toIdx = args.indexOf("--to");
+    const file = args[args.length - 1];
+    if (fromIdx < 0 || toIdx < 0 || !file) {
+        die("Usage: modelbound-mcp convert --from <ide> --to <ide> <file>");
+    }
+    const from = getAdapter(args[fromIdx + 1]);
+    const to = getAdapter(args[toIdx + 1]);
+    if (!from || !to)
+        die(`Unknown adapter. Known: ${ALL_ADAPTERS.map((a) => a.id).join(", ")}`);
+    const canonical = from.toCanonical(fs.readFileSync(file, "utf8"));
+    process.stdout.write(to.fromCanonical(canonical));
+}
+else if (cmd === "detect") {
+    const adapters = detectAdapters(process.cwd());
+    console.log(adapters.length
+        ? adapters.map((a) => `${a.id}\t${a.skillsDir}`).join("\n")
+        : "No known IDE layouts detected.");
+}
+else if (cmd === "ls") {
+    for (const a of detectAdapters(process.cwd())) {
+        for (const f of listAdapterFiles(a, process.cwd())) {
+            console.log(`${a.id}\t${path.relative(process.cwd(), f)}`);
+        }
+    }
+}
+else if (cmd === "--help" || cmd === "-h") {
+    console.log(`modelbound-mcp — local-first MCP server + CLI for agent skills
+
+Without arguments, launches the MCP stdio server (used by IDEs).
+
+Subcommands:
+  detect                          List IDE layouts found in the current directory
+  ls                              List all skill files across detected layouts
+  validate <file>                 Validate a skill against the agentskills.io standard
+  lint <file|dir>                 Run the full linter (front-matter, size, links, TODOs)
+  convert --from X --to Y <file>  Convert between IDE formats (writes to stdout)
+
+Adapters: ${ALL_ADAPTERS.map((a) => a.id).join(", ")}
+
+Set MODELBOUND_API_KEY to unlock cloud sync tools when running as an MCP server.
+`);
+}
+else {
+    die(`Unknown subcommand: ${cmd}. Try --help.`);
+}
+function die(msg) {
+    console.error(msg);
+    process.exit(2);
+}
+function walk(dir) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") && entry.name !== ".cursor" && entry.name !== ".claude" && entry.name !== ".kiro" && entry.name !== ".windsurf")
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walk(full));
+        else if (entry.isFile())
+            out.push(full);
+    }
+    return out;
+}
+function printReport(file, report) {
+    const tag = report.ok ? "OK  " : "FAIL";
+    console.log(`${tag}  ${file}  (~${report.tokens} tokens)`);
+    for (const i of report.issues) {
+        console.log(`  ${i.severity.padEnd(5)} ${i.rule.padEnd(22)} ${i.message}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/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 { localTools } from "./tools/local.js";
+import { cloudTools } from "./tools/cloud.js";
+import { CloudClient } from "./proxy.js";
+const cwd = process.cwd();
+const cloud = CloudClient.fromEnv();
+const tools = [
+    ...localTools(cloud),
+    ...cloudTools(cloud).map((t) => ({
+        ...t,
+        handler: async (args, _ctx) => t.handler(args),
+    })),
+];
+const server = new Server({ name: "modelbound-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = tools.find((t) => t.name === req.params.name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+        };
+    }
+    try {
+        const result = await tool.handler(req.params.arguments ?? {}, { cwd });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: err.message }],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lib/lint.d.ts

@@ -0,0 +1,26 @@
+/** Rough token estimate: 1 token ≈ 4 characters of English text. */
+export declare function estimateTokens(text: string): number;
+export interface LintIssue {
+    severity: "error" | "warn" | "info";
+    rule: string;
+    message: string;
+}
+export interface LintReport {
+    ok: boolean;
+    tokens: number;
+    issues: LintIssue[];
+}
+/**
+ * Lints a single skill file. Catches: missing required front-matter,
+ * suspicious token counts, obviously broken links, and stale TODOs.
+ *
+ * Pure: no network, no filesystem writes.
+ */
+export declare function lintSkill(raw: string, opts?: {
+    maxTokens?: number;
+}): LintReport;
+/**
+ * Validates a skill against the agentskills.io standard:
+ * https://agentskills.io — SKILL.md + front-matter (name, description, optional version).
+ */
+export declare function validateAgentSkillsFormat(raw: string): LintReport;

package/dist/lib/lint.js

@@ -0,0 +1,110 @@
+import matter from "gray-matter";
+/** Rough token estimate: 1 token ≈ 4 characters of English text. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+const LINK_RE = /\[[^\]]+\]\((?<href>[^)]+)\)/g;
+const REQUIRED_FRONTMATTER = ["name", "description"];
+/**
+ * Lints a single skill file. Catches: missing required front-matter,
+ * suspicious token counts, obviously broken links, and stale TODOs.
+ *
+ * Pure: no network, no filesystem writes.
+ */
+export function lintSkill(raw, opts) {
+    const issues = [];
+    const maxTokens = opts?.maxTokens ?? 4000;
+    let frontmatter = {};
+    let body = raw;
+    try {
+        const parsed = matter(raw);
+        frontmatter = parsed.data ?? {};
+        body = parsed.content;
+    }
+    catch (err) {
+        issues.push({
+            severity: "error",
+            rule: "frontmatter-parse",
+            message: `Front-matter could not be parsed: ${err.message}`,
+        });
+    }
+    for (const key of REQUIRED_FRONTMATTER) {
+        if (!frontmatter[key] || typeof frontmatter[key] !== "string") {
+            issues.push({
+                severity: "warn",
+                rule: "frontmatter-required",
+                message: `Missing recommended front-matter field: \`${key}\``,
+            });
+        }
+    }
+    const tokens = estimateTokens(body);
+    if (tokens > maxTokens) {
+        issues.push({
+            severity: "warn",
+            rule: "size",
+            message: `Skill body is ~${tokens} tokens (limit ${maxTokens}). Consider splitting.`,
+        });
+    }
+    for (const match of body.matchAll(LINK_RE)) {
+        const href = match.groups?.href ?? "";
+        if (!href || href.includes(" ") || href === "#") {
+            issues.push({
+                severity: "info",
+                rule: "broken-link",
+                message: `Suspicious link target: \`${href}\``,
+            });
+        }
+    }
+    if (/\bTODO\b|\bFIXME\b/i.test(body)) {
+        issues.push({
+            severity: "info",
+            rule: "todo",
+            message: "Contains TODO/FIXME markers.",
+        });
+    }
+    return {
+        ok: !issues.some((i) => i.severity === "error"),
+        tokens,
+        issues,
+    };
+}
+/**
+ * Validates a skill against the agentskills.io standard:
+ * https://agentskills.io — SKILL.md + front-matter (name, description, optional version).
+ */
+export function validateAgentSkillsFormat(raw) {
+    const issues = [];
+    let frontmatter = {};
+    try {
+        frontmatter = matter(raw).data ?? {};
+    }
+    catch (err) {
+        issues.push({
+            severity: "error",
+            rule: "frontmatter-parse",
+            message: err.message,
+        });
+    }
+    if (!frontmatter.name) {
+        issues.push({ severity: "error", rule: "agentskills-name", message: "`name` is required." });
+    }
+    if (!frontmatter.description) {
+        issues.push({
+            severity: "error",
+            rule: "agentskills-description",
+            message: "`description` is required.",
+        });
+    }
+    if (frontmatter.name && String(frontmatter.name).length > 64) {
+        issues.push({
+            severity: "warn",
+            rule: "agentskills-name-length",
+            message: "`name` should be 64 characters or fewer.",
+        });
+    }
+    return {
+        ok: !issues.some((i) => i.severity === "error"),
+        tokens: estimateTokens(raw),
+        issues,
+    };
+}

package/dist/proxy.d.ts

@@ -0,0 +1,7 @@
+export declare class CloudClient {
+    private apiKey;
+    constructor(apiKey: string);
+    static fromEnv(): CloudClient | null;
+    call(method: string, params: unknown): Promise<unknown>;
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+}

package/dist/proxy.js

@@ -0,0 +1,40 @@
+/**
+ * Thin JSON-RPC 2.0 client for the hosted ModelBound MCP server.
+ *
+ * The URL is hardcoded on purpose: users shouldn't point this at arbitrary
+ * servers from inside their IDE. To self-host, fork this file.
+ */
+const MCP_URL = "https://mcp.modelbound.co/mcp?source=oss-mcp";
+let nextId = 1;
+export class CloudClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    static fromEnv() {
+        const key = process.env.MODELBOUND_API_KEY;
+        return key ? new CloudClient(key) : null;
+    }
+    async call(method, params) {
+        const res = await fetch(MCP_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                // MCP Streamable HTTP servers reject without both Accept types.
+                Accept: "application/json, text/event-stream",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method, params }),
+        });
+        if (!res.ok) {
+            throw new Error(`ModelBound cloud returned ${res.status}: ${await res.text()}`);
+        }
+        const body = (await res.json());
+        if (body.error)
+            throw new Error(body.error.message);
+        return body.result;
+    }
+    async callTool(name, args) {
+        return this.call("tools/call", { name, arguments: args });
+    }
+}

package/dist/tools/cloud.d.ts

@@ -0,0 +1,72 @@
+import { CloudClient } from "../proxy.js";
+export declare function cloudTools(client: CloudClient | null): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            slug: {
+                type: string;
+            };
+            title?: undefined;
+            body_md?: undefined;
+            q?: undefined;
+        };
+        required: string[];
+    };
+    handler: (args: {
+        slug: string;
+    }) => Promise<unknown>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            slug: {
+                type: string;
+            };
+            title: {
+                type: string;
+            };
+            body_md: {
+                type: string;
+            };
+            q?: undefined;
+        };
+        required: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            slug?: undefined;
+            title?: undefined;
+            body_md?: undefined;
+            q?: undefined;
+        };
+        required?: undefined;
+    };
+    handler: () => Promise<unknown>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            q: {
+                type: string;
+            };
+            slug?: undefined;
+            title?: undefined;
+            body_md?: undefined;
+        };
+        required: string[];
+    };
+    handler: (args: {
+        q: string;
+    }) => Promise<unknown>;
+})[];

package/dist/tools/cloud.js

@@ -0,0 +1,66 @@
+const requireCloud = (client) => {
+    if (!client) {
+        throw new Error("This tool requires MODELBOUND_API_KEY. Get one at https://modelbound.co/settings/api-keys");
+    }
+    return client;
+};
+export function cloudTools(client) {
+    return [
+        {
+            name: "pull_skill",
+            description: "Pull a skill from the ModelBound cloud library. Requires MODELBOUND_API_KEY.",
+            inputSchema: {
+                type: "object",
+                properties: { slug: { type: "string" } },
+                required: ["slug"],
+            },
+            handler: async (args) => requireCloud(client).callTool("get_skill", { slug: args.slug }),
+        },
+        {
+            name: "push_skill",
+            description: "Create or update a skill in the cloud library. Requires MODELBOUND_API_KEY.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    slug: { type: "string" },
+                    title: { type: "string" },
+                    body_md: { type: "string" },
+                },
+                required: ["slug", "body_md"],
+            },
+            handler: async (args) => requireCloud(client).callTool("sync_file", args),
+        },
+        {
+            name: "list_cloud_skills",
+            description: "List skills in the cloud library. Requires MODELBOUND_API_KEY.",
+            inputSchema: { type: "object", properties: {} },
+            handler: async () => requireCloud(client).callTool("list_skills", {}),
+        },
+        {
+            name: "search_cloud",
+            description: "Full-text search across all cloud content. Requires MODELBOUND_API_KEY.",
+            inputSchema: {
+                type: "object",
+                properties: { q: { type: "string" } },
+                required: ["q"],
+            },
+            handler: async (args) => requireCloud(client).callTool("search_all", { query: args.q }),
+        },
+        {
+            name: "install_marketplace_skill",
+            description: "Install a public marketplace skill into your library. Requires MODELBOUND_API_KEY.",
+            inputSchema: {
+                type: "object",
+                properties: { slug: { type: "string" } },
+                required: ["slug"],
+            },
+            handler: async (args) => requireCloud(client).callTool("install_skill", { slug: args.slug }),
+        },
+        {
+            name: "get_context_health",
+            description: "Get token health scores and staleness for your context library. Requires MODELBOUND_API_KEY.",
+            inputSchema: { type: "object", properties: {} },
+            handler: async () => requireCloud(client).callTool("get_context_health", {}),
+        },
+    ];
+}

package/dist/tools/local.d.ts

@@ -0,0 +1,271 @@
+import { CloudClient } from "../proxy.js";
+export declare function localTools(cloud?: CloudClient | null): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            adapter?: undefined;
+            path?: undefined;
+            contents?: undefined;
+            maxTokens?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+            slug?: undefined;
+        };
+        additionalProperties: boolean;
+        required?: undefined;
+    };
+    handler: (_args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        cwd: string;
+        detected: {
+            id: string;
+            name: string;
+            skillsDir: string;
+            fileExt: string;
+        }[];
+        knownAdapters: string[];
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            adapter: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            contents?: undefined;
+            maxTokens?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+            slug?: undefined;
+        };
+        additionalProperties: boolean;
+        required?: undefined;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        count: number;
+        files: {
+            adapter: string;
+            path: string;
+            bytes: number;
+        }[];
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description?: undefined;
+            };
+            adapter?: undefined;
+            contents?: undefined;
+            maxTokens?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+            slug?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        path: string;
+        contents: string;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description?: undefined;
+            };
+            contents: {
+                type: string;
+            };
+            adapter?: undefined;
+            maxTokens?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+            slug?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        path: string;
+        bytes: number;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description?: undefined;
+            };
+            maxTokens: {
+                type: string;
+            };
+            adapter?: undefined;
+            contents?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+            slug?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        ok: boolean;
+        tokens: number;
+        issues: import("../lib/lint.js").LintIssue[];
+        path: string;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description?: undefined;
+            };
+            adapter?: undefined;
+            contents?: undefined;
+            maxTokens?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+            slug?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        ok: boolean;
+        tokens: number;
+        issues: import("../lib/lint.js").LintIssue[];
+        path: string;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description?: undefined;
+            };
+            from: {
+                type: string;
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            outPath: {
+                type: string;
+                description: string;
+            };
+            adapter?: undefined;
+            contents?: undefined;
+            maxTokens?: undefined;
+            slug?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        from: string;
+        to: string;
+        wrote: string;
+        bytes: number;
+        contents?: undefined;
+    } | {
+        from: string;
+        to: string;
+        contents: string;
+        wrote?: undefined;
+        bytes?: undefined;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            slug: {
+                type: string;
+                description: string;
+            };
+            adapter?: undefined;
+            contents?: undefined;
+            maxTokens?: undefined;
+            from?: undefined;
+            to?: undefined;
+            outPath?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    handler: (args: unknown, ctx: {
+        cwd: string;
+    }) => Promise<{
+        path: string;
+        slug: string;
+        local_only: boolean;
+        local_bytes: number;
+        note: string;
+        identical?: undefined;
+        remote_bytes?: undefined;
+        local?: undefined;
+        remote?: undefined;
+    } | {
+        path: string;
+        slug: string;
+        identical: boolean;
+        local_bytes: number;
+        remote_bytes: number;
+        local: string;
+        remote: any;
+        local_only?: undefined;
+        note?: undefined;
+    }>;
+})[];

package/dist/tools/local.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ALL_ADAPTERS, detectAdapters, getAdapter, listAdapterFiles } from "../adapters/index.js";
+import { lintSkill, validateAgentSkillsFormat } from "../lib/lint.js";
+import { CloudClient } from "../proxy.js";
+const inside = (cwd, p) => {
+    const abs = path.resolve(cwd, p);
+    if (!abs.startsWith(path.resolve(cwd) + path.sep) && abs !== path.resolve(cwd)) {
+        throw new Error(`Path escapes working directory: ${p}`);
+    }
+    return abs;
+};
+export function localTools(cloud = CloudClient.fromEnv()) {
+    return [
+        {
+            name: "detect_ide_layout",
+            description: "Detect which IDE skill/rule layouts exist in the current working directory. Returns the list of matching adapters (e.g. cursor, claude, kiro). Local-only, no network.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            handler: async (_args, ctx) => {
+                const adapters = detectAdapters(ctx.cwd);
+                return {
+                    cwd: ctx.cwd,
+                    detected: adapters.map((a) => ({
+                        id: a.id,
+                        name: a.name,
+                        skillsDir: a.skillsDir,
+                        fileExt: a.fileExt,
+                    })),
+                    knownAdapters: ALL_ADAPTERS.map((a) => a.id),
+                };
+            },
+        },
+        {
+            name: "list_local_skills",
+            description: "List all skill / rule files found in the detected IDE directories under the current working directory.",
+            inputSchema: {
+                type: "object",
+                properties: { adapter: { type: "string", description: "Optional adapter id to scope the listing." } },
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { adapter } = z.object({ adapter: z.string().optional() }).parse(args ?? {});
+                const adapters = adapter ? [getAdapter(adapter)].filter(Boolean) : detectAdapters(ctx.cwd);
+                const files = [];
+                for (const a of adapters) {
+                    if (!a)
+                        continue;
+                    for (const abs of listAdapterFiles(a, ctx.cwd)) {
+                        files.push({
+                            adapter: a.id,
+                            path: path.relative(ctx.cwd, abs),
+                            bytes: fs.statSync(abs).size,
+                        });
+                    }
+                }
+                return { count: files.length, files };
+            },
+        },
+        {
+            name: "read_local_skill",
+            description: "Read a local skill file (raw contents). Path must be inside the current working directory.",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { path: p } = z.object({ path: z.string().min(1) }).parse(args);
+                const abs = inside(ctx.cwd, p);
+                return { path: p, contents: fs.readFileSync(abs, "utf8") };
+            },
+        },
+        {
+            name: "write_local_skill",
+            description: "Write a local skill file. Creates parent directories. Path must be inside the current working directory.",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string" }, contents: { type: "string" } },
+                required: ["path", "contents"],
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { path: p, contents } = z
+                    .object({ path: z.string().min(1), contents: z.string() })
+                    .parse(args);
+                const abs = inside(ctx.cwd, p);
+                fs.mkdirSync(path.dirname(abs), { recursive: true });
+                fs.writeFileSync(abs, contents, "utf8");
+                return { path: p, bytes: Buffer.byteLength(contents, "utf8") };
+            },
+        },
+        {
+            name: "lint_skill",
+            description: "Lint a skill file: front-matter, token count, broken links, TODO markers. Local-only.",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string" }, maxTokens: { type: "number" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { path: p, maxTokens } = z
+                    .object({ path: z.string().min(1), maxTokens: z.number().optional() })
+                    .parse(args);
+                const abs = inside(ctx.cwd, p);
+                const raw = fs.readFileSync(abs, "utf8");
+                return { path: p, ...lintSkill(raw, { maxTokens }) };
+            },
+        },
+        {
+            name: "validate_skill_format",
+            description: "Validate a skill file against the agentskills.io standard.",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { path: p } = z.object({ path: z.string().min(1) }).parse(args);
+                const abs = inside(ctx.cwd, p);
+                return { path: p, ...validateAgentSkillsFormat(fs.readFileSync(abs, "utf8")) };
+            },
+        },
+        {
+            name: "convert_skill",
+            description: "Convert a skill file from one IDE format to another (e.g. cursor → claude). Round-trips through a canonical {frontmatter, body} representation.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                    from: { type: "string", description: "Source adapter id (e.g. cursor)" },
+                    to: { type: "string", description: "Target adapter id (e.g. claude)" },
+                    outPath: { type: "string", description: "Optional output path. If omitted, returns the converted body without writing." },
+                },
+                required: ["path", "from", "to"],
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { path: p, from, to, outPath } = z
+                    .object({
+                    path: z.string().min(1),
+                    from: z.string(),
+                    to: z.string(),
+                    outPath: z.string().optional(),
+                })
+                    .parse(args);
+                const src = getAdapter(from);
+                const dst = getAdapter(to);
+                if (!src)
+                    throw new Error(`Unknown source adapter: ${from}`);
+                if (!dst)
+                    throw new Error(`Unknown target adapter: ${to}`);
+                const abs = inside(ctx.cwd, p);
+                const raw = fs.readFileSync(abs, "utf8");
+                const canonical = src.toCanonical(raw);
+                const converted = dst.fromCanonical(canonical);
+                if (outPath) {
+                    const outAbs = inside(ctx.cwd, outPath);
+                    fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+                    fs.writeFileSync(outAbs, converted, "utf8");
+                    return { from, to, wrote: outPath, bytes: Buffer.byteLength(converted, "utf8") };
+                }
+                return { from, to, contents: converted };
+            },
+        },
+        {
+            name: "diff_skill",
+            description: "Diff a local skill file against its cloud counterpart by slug. Local-side diff is computed here; the cloud half requires MODELBOUND_API_KEY.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Local skill file path." },
+                    slug: { type: "string", description: "Cloud skill slug to compare against." },
+                },
+                required: ["path", "slug"],
+                additionalProperties: false,
+            },
+            handler: async (args, ctx) => {
+                const { path: p, slug } = z
+                    .object({ path: z.string().min(1), slug: z.string().min(1) })
+                    .parse(args);
+                const abs = inside(ctx.cwd, p);
+                const local = fs.readFileSync(abs, "utf8");
+                if (!cloud) {
+                    return {
+                        path: p,
+                        slug,
+                        local_only: true,
+                        local_bytes: Buffer.byteLength(local, "utf8"),
+                        note: "MODELBOUND_API_KEY not set; returning local file only.",
+                    };
+                }
+                const remote = await cloud.callTool("get_skill", { slug });
+                const remoteBody = typeof remote === "string"
+                    ? remote
+                    : remote?.body_md ?? JSON.stringify(remote, null, 2);
+                return {
+                    path: p,
+                    slug,
+                    identical: local.trim() === String(remoteBody).trim(),
+                    local_bytes: Buffer.byteLength(local, "utf8"),
+                    remote_bytes: Buffer.byteLength(String(remoteBody), "utf8"),
+                    local,
+                    remote: remoteBody,
+                };
+            },
+        }
+    ];
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "modelbound-mcp",
+  "version": "0.1.0",
+  "description": "Local-first MCP server for agent skills. Validate, lint, diff, and convert skills across Cursor, Claude, Kiro, Windsurf, VS Code, and Amazon Q. Optional cloud sync with ModelBound.",
+  "type": "module",
+  "bin": {
+    "modelbound-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --test --import tsx ./src/**/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent-skills",
+    "cursor",
+    "claude",
+    "kiro",
+    "windsurf",
+    "modelbound"
+  ],
+  "author": "ModelBound",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ModelBound/modelbound-mcp-server.git"
+  },
+  "homepage": "https://modelbound.co/open-source",
+  "bugs": {
+    "url": "https://github.com/ModelBound/modelbound-mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}