@promptingbox/mcp 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @promptingbox/mcp
+
+MCP (Model Context Protocol) server for [PromptingBox](https://www.promptingbox.com) — save prompts directly from Claude, Cursor, ChatGPT, and other MCP-compatible AI tools.
+
+## Setup
+
+### 1. Get your API key
+
+Go to [PromptingBox Settings → MCP Integration](https://www.promptingbox.com/workspace/settings?view=mcp) and create an API key.
+
+### 2. Configure your AI tool
+
+> **Tip:** Name the server `pbox` so you can naturally say things like *"save this to pbox"* or *"list my pbox prompts"*.
+
+#### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "pbox": {
+      "command": "npx",
+      "args": ["-y", "@promptingbox/mcp"],
+      "env": {
+        "PROMPTINGBOX_API_KEY": "pb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` in your project (or global config):
+
+```json
+{
+  "mcpServers": {
+    "pbox": {
+      "command": "npx",
+      "args": ["-y", "@promptingbox/mcp"],
+      "env": {
+        "PROMPTINGBOX_API_KEY": "pb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `.claude/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "pbox": {
+      "command": "npx",
+      "args": ["-y", "@promptingbox/mcp"],
+      "env": {
+        "PROMPTINGBOX_API_KEY": "pb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart your AI tool
+
+Restart Claude Desktop or Cursor for the MCP server to be detected.
+
+## Usage
+
+Once configured, you can say things like:
+
+- "Save this prompt to pbox"
+- "Save this as 'Code Review Checklist' in my Work folder on pbox"
+- "List my pbox prompts"
+- "List my pbox folders"
+- "List my pbox tags"
+- "Move prompt [id] to my Work folder on pbox"
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `save_prompt` | Save a prompt with title, content, optional folder and tags |
+| `list_prompts` | List all your prompts with their current folder assignment |
+| `list_folders` | List your PromptingBox folders |
+| `list_tags` | List your PromptingBox tags |
+| `move_prompt_to_folder` | Move an existing prompt to a different folder by prompt ID |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PROMPTINGBOX_API_KEY` | Yes | Your PromptingBox API key (starts with `pb_`) |
+| `PROMPTINGBOX_BASE_URL` | No | Override the API base URL (default: `https://www.promptingbox.com`) |
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,45 @@
+export interface PromptingBoxConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface SavePromptParams {
+    title: string;
+    content: string;
+    folder?: string;
+    tagNames?: string[];
+}
+export interface SavePromptResult {
+    id: string;
+    title: string;
+    folderId: string | null;
+    createdAt: string;
+    url: string;
+}
+export interface Folder {
+    id: string;
+    name: string;
+    order: number;
+}
+export interface Tag {
+    id: string;
+    name: string;
+}
+export interface PromptListItem {
+    id: string;
+    title: string;
+    folderId: string | null;
+    folderName: string | null;
+}
+export declare class PromptingBoxClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: PromptingBoxConfig);
+    private request;
+    savePrompt(params: SavePromptParams): Promise<SavePromptResult>;
+    listFolders(): Promise<Folder[]>;
+    listTags(): Promise<Tag[]>;
+    listPrompts(): Promise<PromptListItem[]>;
+    movePromptToFolder(promptId: string, folder: string): Promise<{
+        success: boolean;
+    }>;
+}

package/dist/api-client.js

@@ -0,0 +1,46 @@
+const DEFAULT_BASE_URL = 'https://www.promptingbox.com';
+export class PromptingBoxClient {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    }
+    async request(path, options) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            ...options,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+                ...options?.headers,
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`PromptingBox API error ${res.status}: ${body}`);
+        }
+        return res.json();
+    }
+    async savePrompt(params) {
+        return this.request('/api/mcp/prompts', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    async listFolders() {
+        return this.request('/api/mcp/folders');
+    }
+    async listTags() {
+        return this.request('/api/mcp/tags');
+    }
+    async listPrompts() {
+        return this.request('/api/mcp/prompts');
+    }
+    async movePromptToFolder(promptId, folder) {
+        return this.request(`/api/mcp/prompts/${promptId}/folder`, {
+            method: 'PATCH',
+            body: JSON.stringify({ folder }),
+        });
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { PromptingBoxClient } from './api-client.js';
+const API_KEY = process.env.PROMPTINGBOX_API_KEY;
+const BASE_URL = process.env.PROMPTINGBOX_BASE_URL; // optional override
+if (!API_KEY) {
+    process.stderr.write('Error: PROMPTINGBOX_API_KEY environment variable is required.\n' +
+        'Get your API key at https://www.promptingbox.com/workspace/settings?view=mcp\n');
+    process.exit(1);
+}
+const client = new PromptingBoxClient({ apiKey: API_KEY, baseUrl: BASE_URL });
+const server = new McpServer({
+    name: 'promptingbox',
+    version: '0.1.0',
+});
+// ── save_prompt ──────────────────────────────────────────────────────────────
+server.tool('save_prompt', 'Save a prompt to the user\'s PromptingBox account. Use this when the user wants to save, store, or bookmark a prompt.', {
+    title: z.string().describe('A short, descriptive title for the prompt'),
+    content: z.string().describe('The full prompt content to save'),
+    folder: z.string().optional().describe('Folder name to save into (created if it doesn\'t exist)'),
+    tagNames: z.array(z.string()).optional().describe('Tag names to apply (created if they don\'t exist)'),
+}, async ({ title, content, folder, tagNames }) => {
+    try {
+        const result = await client.savePrompt({ title, content, folder, tagNames });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Prompt saved to PromptingBox!\n\nTitle: ${result.title}\nID: ${result.id}\nURL: ${result.url}` +
+                        (result.folderId ? `\nFolder: ${folder}` : ''),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Failed to save prompt: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── list_folders ─────────────────────────────────────────────────────────────
+server.tool('list_folders', 'List all folders in the user\'s PromptingBox account. Useful to know where to save a prompt.', {}, async () => {
+    try {
+        const folders = await client.listFolders();
+        if (folders.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No folders found. You can specify a folder name when saving and it will be created automatically.' }],
+            };
+        }
+        const list = folders.map((f) => `- ${f.name}`).join('\n');
+        return {
+            content: [{ type: 'text', text: `Folders in PromptingBox:\n${list}` }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Failed to list folders: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── list_prompts ─────────────────────────────────────────────────────────────
+server.tool('list_prompts', 'List all prompts in the user\'s PromptingBox account grouped by folder. Use this to see what prompts exist and where they are organized.', {}, async () => {
+    try {
+        const prompts = await client.listPrompts();
+        if (prompts.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No prompts found.' }],
+            };
+        }
+        // Group by folder
+        const grouped = new Map();
+        for (const p of prompts) {
+            const key = p.folderName ?? '(no folder)';
+            if (!grouped.has(key))
+                grouped.set(key, []);
+            grouped.get(key).push(p);
+        }
+        // Sort: named folders first (alphabetical), then unfiled
+        const sortedKeys = [...grouped.keys()].sort((a, b) => {
+            if (a === '(no folder)')
+                return 1;
+            if (b === '(no folder)')
+                return -1;
+            return a.localeCompare(b);
+        });
+        const lines = [`Your PromptingBox prompts (${prompts.length} total):\n`];
+        for (const key of sortedKeys) {
+            lines.push(`📁 ${key}`);
+            for (const p of grouped.get(key)) {
+                lines.push(`   • ${p.title}  [id: ${p.id}]`);
+            }
+            lines.push('');
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n').trimEnd() }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Failed to list prompts: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── move_prompt_to_folder ─────────────────────────────────────────────────
+server.tool('move_prompt_to_folder', 'Move a prompt to a different folder. Provide either the prompt ID or the prompt title — if a title is given, it will be looked up automatically. Does not change or delete prompt content.', {
+    promptId: z.string().optional().describe('The prompt ID (from list_prompts). Provide this or promptTitle.'),
+    promptTitle: z.string().optional().describe('The prompt title to search for. Provide this or promptId.'),
+    folder: z.string().describe('The folder name to move the prompt into'),
+}, async ({ promptId, promptTitle, folder }) => {
+    try {
+        let resolvedId = promptId;
+        if (!resolvedId) {
+            if (!promptTitle) {
+                return {
+                    content: [{ type: 'text', text: 'Provide either promptId or promptTitle.' }],
+                    isError: true,
+                };
+            }
+            const all = await client.listPrompts();
+            const lower = promptTitle.toLowerCase();
+            const matches = all.filter((p) => p.title.toLowerCase().includes(lower));
+            if (matches.length === 0) {
+                return {
+                    content: [{ type: 'text', text: `No prompt found matching "${promptTitle}".` }],
+                    isError: true,
+                };
+            }
+            if (matches.length > 1) {
+                const list = matches.map((p) => `- ${p.title} (id: ${p.id})`).join('\n');
+                return {
+                    content: [{ type: 'text', text: `Multiple prompts match "${promptTitle}". Use promptId to be specific:\n${list}` }],
+                    isError: true,
+                };
+            }
+            resolvedId = matches[0].id;
+        }
+        await client.movePromptToFolder(resolvedId, folder);
+        return {
+            content: [{ type: 'text', text: `Moved prompt to folder "${folder}".` }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Failed to move prompt: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── list_tags ────────────────────────────────────────────────────────────────
+server.tool('list_tags', 'List all tags in the user\'s PromptingBox account. Useful to know what tags are available when saving a prompt.', {}, async () => {
+    try {
+        const tags = await client.listTags();
+        if (tags.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No tags found. You can specify tag names when saving and they will be created automatically.' }],
+            };
+        }
+        const list = tags.map((t) => `- ${t.name}`).join('\n');
+        return {
+            content: [{ type: 'text', text: `Tags in PromptingBox:\n${list}` }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Failed to list tags: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── start server ─────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('PromptingBox MCP server running on stdio\n');
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@promptingbox/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PromptingBox — save prompts from Claude, Cursor, and ChatGPT",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "promptingbox-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "prompts",
+    "claude",
+    "cursor",
+    "chatgpt",
+    "promptingbox",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/promptingbox/promptingbox"
+  },
+  "homepage": "https://www.promptingbox.com"
+}