@snippkit/mcp-server 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SnippKit
+
+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

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @snippkit/mcp-server
+
+Official **Model Context Protocol (MCP)** server for **SnippKit**.
+
+Connect your AI coding agents (**Google Antigravity**, **Cursor**, **Claude Desktop**, **Windsurf**, **Claude Code**) directly to your SnippKit library. Empower your agents with procedural **AI Skills**, verified **Code Snippets**, and executable **Shell Commands**.
+
+---
+
+## ⚡ Quick Start
+
+### 1. Cursor Setup
+Add the following to your Cursor MCP settings (`.cursor/mcp.json` or Settings > Features > MCP):
+
+```json
+{
+  "mcpServers": {
+    "snippkit": {
+      "command": "npx",
+      "args": ["-y", "@snippkit/mcp-server"],
+      "env": {
+        "SNIPPKIT_API_KEY": "sk_live_YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### 2. Claude Desktop Setup
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "snippkit": {
+      "command": "npx",
+      "args": ["-y", "@snippkit/mcp-server"],
+      "env": {
+        "SNIPPKIT_API_KEY": "sk_live_YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### 3. Antigravity & Windsurf Setup
+In your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "snippkit": {
+      "command": "npx",
+      "args": ["-y", "@snippkit/mcp-server"],
+      "env": {
+        "SNIPPKIT_API_KEY": "sk_live_YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Provided Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `snippkit_search_skills` | Search public and team AI Skills in the SnippKit registry by keywords or agent compatibility. |
+| `snippkit_get_skill` | Fetch complete `SKILL.md` instructions and procedural rules to guide agent execution. |
+| `snippkit_search_snippets` | Search your private and public code snippets by title, tag, or language. |
+| `snippkit_get_snippet` | Retrieve decrypted code from your SnippKit library. |
+| `snippkit_save_snippet` | Save newly written or refactored code directly into SnippKit from the agent. |
+| `snippkit_search_commands` | Search verified shell scripts and DevOps command runbooks. |
+| `snippkit_get_command` | Retrieve shell command scripts. |
+
+---
+
+## 📚 Resources & Prompts
+
+- **Resources:**
+  - `snippkit://skills/{slug}`: Read a skill's full instructions as a direct context resource.
+  - `snippkit://snippets/{id}`: Read a snippet as a direct context resource.
+- **Prompts:**
+  - `use-skill`: Injects a named SnippKit skill into the agent's context window.
+  - `save-solution`: Prompts the agent to format and persist code to SnippKit.
+
+---
+
+## 🔐 Authentication
+
+Generate your API key from [SnippKit Dashboard > Settings > Developer Keys](https://snippkit.com/settings/developer).
+
+The server checks credentials in this order:
+1. `SNIPPKIT_API_KEY` environment variable.
+2. Command-line flag `--api-key <key>`.
+3. Local `snix` CLI vault (if you have already logged in via `snix login`).
+
+---
+
+## 📄 License
+
+MIT © [SnippKit](https://snippkit.com)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/bin/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { startServer } from '../src/index.js';
+
+startServer().catch((error) => {
+  console.error('[snippkit-mcp] Fatal server startup error:', error);
+  process.exit(1);
+});
+

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@snippkit/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Official Model Context Protocol (MCP) Server for SnippKit - Seamless integration with AI agents (Cursor, Claude Desktop, Antigravity, Windsurf) for Agent Skills, Code Snippets, and Shell Commands.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "snippkit-mcp": "bin/index.js",
+    "mcp-server": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yaseen549/snippkit-mcp-server.git"
+  },
+  "homepage": "https://snippkit.com",
+  "bugs": {
+    "url": "https://github.com/Yaseen549/snippkit-mcp-server/issues"
+  },
+  "scripts": {
+    "start": "node bin/index.js",
+    "dev": "node bin/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "snippkit",
+    "ai-agent",
+    "ai-skills",
+    "cursor",
+    "claude-desktop",
+    "antigravity",
+    "windsurf"
+  ],
+  "author": "SnippKit",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "axios": "^1.7.9",
+    "conf": "^12.0.0",
+    "zod": "^3.24.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,141 @@
+import axios from 'axios';
+import { getConfig } from './config.js';
+
+export class SnippKitClient {
+  constructor() {
+    const { apiKey, apiUrl } = getConfig();
+    this.apiKey = apiKey;
+    this.apiUrl = apiUrl;
+
+    this.http = axios.create({
+      baseURL: apiUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': '@snippkit/mcp-server/1.0.0',
+      },
+      timeout: 15000,
+    });
+
+    this.http.interceptors.request.use((reqConfig) => {
+      // Re-fetch current config in case updated dynamically
+      const current = getConfig();
+      if (current.apiKey && !reqConfig.headers['Authorization']) {
+        reqConfig.headers['Authorization'] = `Bearer ${current.apiKey}`;
+      }
+      return reqConfig;
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // SKILLS
+  // --------------------------------------------------------------------------
+  async searchSkills({ query = '', agent = '', sort = 'installs', limit = 10 } = {}) {
+    const params = new URLSearchParams();
+    if (query) params.set('q', query);
+    if (agent && agent !== 'all') params.set('agent', agent);
+    if (sort) params.set('sort', sort);
+    if (limit) params.set('limit', String(limit));
+
+    const res = await this.http.get(`/api/skills/search?${params.toString()}`);
+    return res.data;
+  }
+
+  async getSkill({ slug, id, username } = {}) {
+    const target = id || slug;
+    if (!target) throw new Error('Skill slug or ID is required');
+
+    // First try /api/skills/read (full markdown and author details)
+    const params = new URLSearchParams();
+    if (id) params.set('id', id);
+    else if (slug) params.set('slug', slug);
+    if (username) params.set('username', username);
+
+    try {
+      const res = await this.http.get(`/api/skills/read?${params.toString()}`);
+      if (res.data && !res.data.error) {
+        return res.data;
+      }
+    } catch (err) {
+      // Fallback to /api/cli/run?type=skills
+    }
+
+    const fallbackRes = await this.http.get(`/api/cli/run?type=skills&id=${encodeURIComponent(target)}`);
+    return fallbackRes.data;
+  }
+
+  // --------------------------------------------------------------------------
+  // SNIPPETS
+  // --------------------------------------------------------------------------
+  async searchSnippets({ query = '' } = {}) {
+    if (!this.apiKey) {
+      throw new Error('SnippKit API Key is required to search private snippets. Set SNIPPKIT_API_KEY environment variable.');
+    }
+    const params = new URLSearchParams({ type: 'snippets' });
+    if (query) params.set('search', query);
+
+    const res = await this.http.get(`/api/cli/list?${params.toString()}`);
+    return res.data;
+  }
+
+  async getSnippet({ id, slug } = {}) {
+    const target = id || slug;
+    if (!target) throw new Error('Snippet ID or slug is required');
+
+    const res = await this.http.get(`/api/cli/run?type=snippets&id=${encodeURIComponent(target)}`);
+    return res.data;
+  }
+
+  async saveSnippet({ title, code, language = 'plaintext', description = '', is_public = false, tags = [] } = {}) {
+    if (!this.apiKey) {
+      throw new Error('SnippKit API Key is required to save snippets. Set SNIPPKIT_API_KEY environment variable.');
+    }
+    if (!title) throw new Error('Snippet title is required');
+    if (!code) throw new Error('Snippet code is required');
+
+    const payload = {
+      title,
+      code,
+      language: language.toLowerCase(),
+      description,
+      is_public: Boolean(is_public),
+      tags: Array.isArray(tags) ? tags : [],
+    };
+
+    const res = await this.http.post('/api/s/create', payload);
+    return res.data;
+  }
+
+  // --------------------------------------------------------------------------
+  // COMMANDS
+  // --------------------------------------------------------------------------
+  async searchCommands({ query = '' } = {}) {
+    if (!this.apiKey) {
+      throw new Error('SnippKit API Key is required to search commands. Set SNIPPKIT_API_KEY environment variable.');
+    }
+    const params = new URLSearchParams({ type: 'commands' });
+    if (query) params.set('search', query);
+
+    const res = await this.http.get(`/api/cli/list?${params.toString()}`);
+    return res.data;
+  }
+
+  async getCommand({ id, slug } = {}) {
+    const target = id || slug;
+    if (!target) throw new Error('Command ID or slug is required');
+
+    const res = await this.http.get(`/api/cli/run?type=commands&id=${encodeURIComponent(target)}`);
+    return res.data;
+  }
+
+  // --------------------------------------------------------------------------
+  // FOLDERS
+  // --------------------------------------------------------------------------
+  async listFolders() {
+    if (!this.apiKey) {
+      throw new Error('SnippKit API Key is required to list folders. Set SNIPPKIT_API_KEY environment variable.');
+    }
+    const res = await this.http.get('/api/cli/list?type=folders');
+    return res.data;
+  }
+}
+

package/src/config.js

@@ -0,0 +1,90 @@
+import Conf from 'conf';
+import crypto from 'crypto';
+import os from 'os';
+
+// Parse command line arguments for --api-key and --api-url
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--api-key' || arg === '--key') {
+      result.apiKey = args[++i];
+    } else if (arg.startsWith('--api-key=')) {
+      result.apiKey = arg.split('=')[1];
+    } else if (arg === '--api-url' || arg === '--url') {
+      result.apiUrl = args[++i];
+    } else if (arg.startsWith('--api-url=')) {
+      result.apiUrl = arg.split('=')[1];
+    }
+  }
+  return result;
+}
+
+const cliArgs = parseArgs();
+
+// Helper to decrypt key from snix CLI vault if present
+function getDerivedKey() {
+  let user = 'user';
+  try {
+    user = process.env.USERNAME || process.env.USER || os.userInfo()?.username || 'user';
+  } catch (e) {
+    user = process.env.USERNAME || process.env.USER || 'user';
+  }
+  let host = 'localhost';
+  try {
+    host = os.hostname() || process.env.COMPUTERNAME || 'localhost';
+  } catch (e) {
+    host = process.env.COMPUTERNAME || 'localhost';
+  }
+  const cleanUser = String(user).toLowerCase().trim();
+  const cleanHost = String(host).toLowerCase().trim();
+  const machineSecret = `${cleanUser}_${cleanHost}_SNIPPKIT_CLI_V2_VAULT_SECRET`;
+  return crypto.pbkdf2Sync(machineSecret, 'snippkit_v2_salt_secure_vault', 100000, 32, 'sha256');
+}
+
+function readCliVaultKey() {
+  try {
+    const cliConfig = new Conf({
+      projectName: 'snippkit-cli',
+      configFileMode: 0o600
+    });
+
+    const vaultData = cliConfig.get('secureVault');
+    if (!vaultData || !vaultData.iv || !vaultData.authTag || !vaultData.ciphertext) {
+      // Fallback to legacy plaintext if any
+      const legacyKey = cliConfig.get('apiKey');
+      return typeof legacyKey === 'string' ? legacyKey.trim() : null;
+    }
+
+    const key = getDerivedKey();
+    const iv = Buffer.from(vaultData.iv, 'hex');
+    const authTag = Buffer.from(vaultData.authTag, 'hex');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(vaultData.ciphertext, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted || null;
+  } catch {
+    return null;
+  }
+}
+
+export function getConfig() {
+  const apiKey =
+    cliArgs.apiKey ||
+    process.env.SNIPPKIT_API_KEY ||
+    process.env.SNIPPKIT_KEY ||
+    readCliVaultKey() ||
+    null;
+
+  const apiUrl = (
+    cliArgs.apiUrl ||
+    process.env.SNIPPKIT_API_URL ||
+    process.env.SNIPPKIT_BASE_URL ||
+    'https://snippkit.com'
+  ).replace(/\/+$/, '');
+
+  return { apiKey, apiUrl };
+}
+

package/src/index.js

@@ -0,0 +1,58 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { SnippKitClient } from './client.js';
+import { getConfig } from './config.js';
+import { registerSkillTools } from './tools/skills.js';
+import { registerSnippetTools } from './tools/snippets.js';
+import { registerCommandTools } from './tools/commands.js';
+import { registerResources } from './resources/index.js';
+import { registerPrompts } from './prompts/index.js';
+
+export function createServer() {
+  const config = getConfig();
+  const client = new SnippKitClient();
+
+  const server = new McpServer(
+    {
+      name: 'snippkit',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+        logging: {},
+      },
+    }
+  );
+
+  // Register all capabilities
+  registerSkillTools(server, client);
+  registerSnippetTools(server, client);
+  registerCommandTools(server, client);
+  registerResources(server, client);
+  registerPrompts(server, client);
+
+  return { server, client, config };
+}
+
+export async function startServer() {
+  const { server, config } = createServer();
+  const transport = new StdioServerTransport();
+
+  // Log diagnostic info to stderr (stdout is strictly reserved for JSON-RPC MCP messages!)
+  console.error('[snippkit-mcp] Initializing SnippKit MCP Server v1.0.0...');
+  console.error(`[snippkit-mcp] API Endpoint: ${config.apiUrl}`);
+  if (config.apiKey) {
+    const masked = `${config.apiKey.slice(0, 7)}...${config.apiKey.slice(-4)}`;
+    console.error(`[snippkit-mcp] Authentication: Configured (${masked})`);
+  } else {
+    console.error('[snippkit-mcp] Authentication: Public access only (Set SNIPPKIT_API_KEY for private snippets)');
+  }
+
+  await server.connect(transport);
+  console.error('[snippkit-mcp] Connected over stdio transport. Listening for agent requests.');
+}
+

package/src/prompts/index.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+export function registerPrompts(server, client) {
+  // 1. Prompt: use-skill
+  server.prompt(
+    'use-skill',
+    'Load and apply a procedural AI skill from SnippKit into your context window.',
+    {
+      slug: z.string().describe("The slug or identifier of the skill to apply (e.g. 'hello-world')"),
+    },
+    async ({ slug }) => {
+      try {
+        const skill = await client.getSkill({ slug });
+        const title = skill?.title || slug;
+        const content = skill?.content || skill?.description || 'No instructions found.';
+
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `I want you to follow the rules and procedures from the SnippKit Skill "${title}".
+
+Instructions from SKILL.md:
+================================================================================
+${content}
+================================================================================
+
+Please confirm you have read and understood these instructions before proceeding.`,
+              },
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Please fetch and apply the skill "${slug}" from SnippKit. (Auto-fetch failed: ${err.message})`,
+              },
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // 2. Prompt: save-solution
+  server.prompt(
+    'save-solution',
+    'Prompt the AI agent to review the code just written and save it as a reusable snippet in SnippKit.',
+    {
+      title: z.string().optional().describe('Proposed title for the snippet'),
+      language: z.string().optional().describe('Programming language'),
+    },
+    async ({ title = '', language = '' }) => {
+      return {
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `Please review the code we just developed. Format it cleanly, add comments explaining how to use it, and save it to my SnippKit library using \`snippkit_save_snippet\` with:
+- Title: ${title || 'Meaningful, descriptive title'}
+- Language: ${language || 'appropriate programming language'}
+- Description: summary of why this code works and when to reuse it`,
+            },
+          },
+        ],
+      };
+    }
+  );
+}
+

package/src/resources/index.js

@@ -0,0 +1,66 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+export function registerResources(server, client) {
+  // 1. Skill Resource: snippkit://skills/{slug}
+  server.resource(
+    'skill',
+    new ResourceTemplate('snippkit://skills/{slug}', { list: undefined }),
+    async (uri, { slug }) => {
+      try {
+        const skill = await client.getSkill({ slug });
+        const content = skill?.content || skill?.description || 'No content found';
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              text: content,
+              mimeType: 'text/markdown',
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              text: `Error loading skill "${slug}": ${err.message}`,
+              mimeType: 'text/plain',
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // 2. Snippet Resource: snippkit://snippets/{id}
+  server.resource(
+    'snippet',
+    new ResourceTemplate('snippkit://snippets/{id}', { list: undefined }),
+    async (uri, { id }) => {
+      try {
+        const snip = await client.getSnippet({ id });
+        const code = snip?.code || snip?.snippet?.code || '';
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              text: code,
+              mimeType: 'text/plain',
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              text: `Error loading snippet "${id}": ${err.message}`,
+              mimeType: 'text/plain',
+            },
+          ],
+        };
+      }
+    }
+  );
+}
+

package/src/tools/commands.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+
+export function registerCommandTools(server, client) {
+  // 1. Search Commands
+  server.tool(
+    'snippkit_search_commands',
+    'Search verified shell commands, deployment scripts, and terminal runbooks stored in your SnippKit library.',
+    {
+      query: z.string().optional().describe("Search keywords, e.g. 'docker', 'git', 'kubectl', 'npm'"),
+    },
+    async ({ query = '' }) => {
+      try {
+        const commands = await client.searchCommands({ query });
+        if (!Array.isArray(commands) || commands.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No shell commands found matching "${query}".`,
+              },
+            ],
+          };
+        }
+
+        const formatted = commands.map((c) => {
+          const lines = Array.isArray(c.commands) ? c.commands : [];
+          return `- **${c.title}**
+  ID: \`${c.id}\` | Slug: \`${c.slug || 'n/a'}\`
+  Steps: ${c.command_count || lines.length}
+  Preview: \`${lines[0] || 'N/A'}\`
+`;
+        }).join('\n');
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Found ${commands.length} command runbook(s) in your SnippKit library:\n\n${formatted}\n\n*Tip: Call \`snippkit_get_command\` with an ID to inspect the full script.*`,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to search commands: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // 2. Get Command
+  server.tool(
+    'snippkit_get_command',
+    'Retrieve the shell commands/scripts from a runbook in SnippKit by ID or slug.',
+    {
+      id: z.string().describe('Command runbook UUID or slug'),
+    },
+    async ({ id }) => {
+      try {
+        const result = await client.getCommand({ id });
+        if (!result) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: `Command "${id}" not found.` }],
+          };
+        }
+
+        const title = result.title || 'Command Runbook';
+        const lines = Array.isArray(result.commands)
+          ? result.commands.join('\n')
+          : result.command || result.commands || '';
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `### Command: ${title}\n\n\`\`\`bash\n${lines}\n\`\`\``,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to fetch command "${id}": ${err.message}` }],
+        };
+      }
+    }
+  );
+}
+

package/src/tools/skills.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+
+export function registerSkillTools(server, client) {
+  // 1. Search Skills
+  server.tool(
+    'snippkit_search_skills',
+    'Search the SnippKit AI Skills Registry for agent capabilities, procedural rules, and autonomous instructions.',
+    {
+      query: z.string().optional().describe("Search keywords, e.g. 'supabase', 'nextjs', 'docker', 'auth'"),
+      agent: z
+        .enum(['all', 'antigravity', 'cursor', 'claude-code', 'windsurf', 'chatgpt', 'gemini-cli'])
+        .optional()
+        .default('all')
+        .describe('Filter by AI agent compatibility'),
+      limit: z.number().int().min(1).max(25).optional().default(10).describe('Max skills to return'),
+    },
+    async ({ query = '', agent = 'all', limit = 10 }) => {
+      try {
+        const skills = await client.searchSkills({ query, agent, limit });
+        if (!Array.isArray(skills) || skills.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No skills found in SnippKit registry matching "${query}". Try searching with broader terms.`,
+              },
+            ],
+          };
+        }
+
+        const formatted = skills.map((s) => {
+          const author = s.username || s.author?.username || 'developer';
+          const tags = Array.isArray(s.tags) ? s.tags.map((t) => `#${t}`).join(' ') : '';
+          return `### ${s.title} (v${s.version || '1.0.0'})
+- **Slug / ID**: \`@${author}/${s.slug || s.id}\`
+- **Description**: ${s.description || 'No description provided'}
+- **Compatibility**: ${(s.compatibility || []).join(', ') || 'universal'}
+- **Downloads**: ${s.downloads || 0} installs | **Stars**: ${s.stars || 0}
+- **Tags**: ${tags || 'none'}
+- **Install CLI**: \`snix skill add @${author}/${s.slug || s.id}\`
+`;
+        }).join('\n---\n\n');
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Found ${skills.length} matching skill(s) in SnippKit Registry:\n\n${formatted}\n\n*Tip: Call \`snippkit_get_skill\` with a slug to fetch the full instructions.*`,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to search skills: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // 2. Get Skill
+  server.tool(
+    'snippkit_get_skill',
+    'Fetch the complete SKILL.md instructions and procedural rules for an AI skill from SnippKit. Use this to guide your execution with expert domain knowledge.',
+    {
+      slug: z.string().describe("The slug or identifier of the skill (e.g. 'hello-world' or '@username/slug')"),
+      username: z.string().optional().describe('Author username if known'),
+    },
+    async ({ slug, username }) => {
+      try {
+        const skill = await client.getSkill({ slug, username });
+        if (!skill) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: `Skill "${slug}" was not found or is private.` }],
+          };
+        }
+
+        const author = skill.username || skill.author?.username || username || 'developer';
+        const header = `# Skill: ${skill.title} (v${skill.version || '1.0.0'})
+Author: @${author}
+Slug: ${skill.slug || slug}
+Compatibility: ${(skill.compatibility || []).join(', ') || 'universal'}
+Description: ${skill.description || 'N/A'}
+
+================================================================================
+SKILL.md INSTRUCTIONS
+================================================================================
+`;
+        const content = skill.content || skill.description || 'No instruction body found for this skill.';
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${header}\n${content}`,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to fetch skill "${slug}": ${err.message}` }],
+        };
+      }
+    }
+  );
+}
+

package/src/tools/snippets.js

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+
+export function registerSnippetTools(server, client) {
+  // 1. Search Snippets
+  server.tool(
+    'snippkit_search_snippets',
+    'Search your personal and bookmarked code snippets library in SnippKit by title, language, or keyword.',
+    {
+      query: z.string().optional().describe("Search keywords or language, e.g. 'auth', 'jwt', 'python', 'react'"),
+    },
+    async ({ query = '' }) => {
+      try {
+        const snippets = await client.searchSnippets({ query });
+        if (!Array.isArray(snippets) || snippets.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No snippets found matching "${query}".`,
+              },
+            ],
+          };
+        }
+
+        const formatted = snippets.map((s) => {
+          return `- **${s.title}** (\`${s.language || 'plaintext'}\`)
+  ID: \`${s.id}\` | Slug: \`${s.slug || 'n/a'}\`
+  Public: ${s.is_public ? 'Yes' : 'No (Encrypted)'} | Size: ${s.size_in_bytes || 0} bytes
+`;
+        }).join('\n');
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Found ${snippets.length} snippet(s) in your SnippKit library:\n\n${formatted}\n\n*Tip: Call \`snippkit_get_snippet\` with an ID to read the full code.*`,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to search snippets: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // 2. Get Snippet
+  server.tool(
+    'snippkit_get_snippet',
+    'Retrieve the decrypted source code of a specific code snippet from SnippKit by ID or slug.',
+    {
+      id: z.string().describe('Snippet UUID or slug'),
+    },
+    async ({ id }) => {
+      try {
+        const result = await client.getSnippet({ id });
+        if (!result) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: `Snippet "${id}" not found.` }],
+          };
+        }
+
+        const title = result.title || 'Untitled Snippet';
+        const lang = result.language || 'plaintext';
+        const code = result.code || result.snippet?.code || '';
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `### Snippet: ${title} (${lang})\n\n\`\`\`${lang}\n${code}\n\`\`\``,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to fetch snippet "${id}": ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  // 3. Save Snippet
+  server.tool(
+    'snippkit_save_snippet',
+    'Save newly generated or refactored code directly into your SnippKit library. Persists solutions across your projects and environments.',
+    {
+      title: z.string().describe('Clear, descriptive title for the snippet'),
+      code: z.string().describe('The source code to save'),
+      language: z.string().optional().default('plaintext').describe("Programming language (e.g. 'typescript', 'python', 'sql', 'bash')"),
+      description: z.string().optional().describe('Brief explanation of what this code does and when to use it'),
+      is_public: z.boolean().optional().default(false).describe('Set to true for public snippet, false for zero-knowledge encrypted private snippet'),
+      tags: z.array(z.string()).optional().describe('Array of tags for searching'),
+    },
+    async ({ title, code, language = 'plaintext', description = '', is_public = false, tags = [] }) => {
+      try {
+        const saved = await client.saveSnippet({
+          title,
+          code,
+          language,
+          description,
+          is_public,
+          tags,
+        });
+
+        const id = saved.id || saved.snippet?.id || 'created';
+        const slug = saved.slug || saved.snippet?.slug;
+        const link = slug ? `https://snippkit.com/s/${slug}` : `https://snippkit.com/s/${id}`;
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully saved snippet to SnippKit!\n- **Title**: ${title}\n- **Language**: ${language}\n- **Access**: ${is_public ? 'Public' : 'Private (Encrypted)'}\n- **Snippet ID**: \`${id}\`\n- **Web URL**: ${link}`,
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Failed to save snippet to SnippKit: ${err.message}` }],
+        };
+      }
+    }
+  );
+}
+