perceptia-mcp 1.0.0

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { startServer } from "./server.js";
+import { runSetup } from "./setup.js";
+const args = process.argv.slice(2);
+const command = args[0];
+if (command === "setup") {
+    const apiKey = args[1];
+    if (!apiKey) {
+        console.log("Perceptia MCP — Setup");
+        console.log("");
+        console.log("Usage: npx perceptia-mcp setup <API_KEY>");
+        console.log("");
+        console.log("  API_KEY  Your Perceptia API key (starts with ck_live_)");
+        console.log("           Get one at https://perceptiamcp.com/dashboard");
+        process.exit(1);
+    }
+    await runSetup(apiKey);
+}
+else if (command === "help" || command === "--help" || command === "-h") {
+    console.log("Perceptia MCP Server");
+    console.log("");
+    console.log("Commands:");
+    console.log("  setup <API_KEY>  Configure Perceptia for your AI clients");
+    console.log("  (no command)     Run the MCP server (used by AI clients)");
+    console.log("");
+    console.log("Setup:  npx perceptia-mcp setup ck_live_xxx");
+    console.log("Docs:   https://perceptiamcp.com");
+}
+else {
+    // Default: run MCP server via stdio
+    const apiKey = process.env.PERCEPTIA_API_KEY;
+    if (!apiKey) {
+        console.error("Error: PERCEPTIA_API_KEY environment variable is required.");
+        console.error("Run 'npx perceptia-mcp setup <KEY>' to configure automatically.");
+        process.exit(1);
+    }
+    await startServer(apiKey);
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(apiKey: string): Promise<void>;

package/dist/server.js

@@ -0,0 +1,99 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const API_BASE = "https://api.perceptiamcp.com";
+export async function startServer(apiKey) {
+    const server = new Server({ name: "perceptia-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "ground",
+                description: "Get grounding context from Perceptia for a coding query. Returns best-practice guidance relevant to the query.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "The coding topic or question to get grounding for",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "status",
+                description: "Check your Perceptia API usage and device status",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === "ground") {
+            const query = args?.query;
+            if (!query || typeof query !== "string") {
+                return {
+                    content: [{ type: "text", text: "Error: query parameter is required" }],
+                    isError: true,
+                };
+            }
+            const fingerprint = `mcp-client-${apiKey.slice(-8)}`;
+            const res = await fetch(`${API_BASE}/v1/ground`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                    "X-Fingerprint": fingerprint,
+                },
+                body: JSON.stringify({ query }),
+            });
+            if (res.status === 401) {
+                return {
+                    content: [{ type: "text", text: "Error: Invalid API key. Check your PERCEPTIA_API_KEY." }],
+                    isError: true,
+                };
+            }
+            if (res.status === 429) {
+                return {
+                    content: [{ type: "text", text: "Error: Monthly quota exceeded. Upgrade your plan at perceptiamcp.com" }],
+                    isError: true,
+                };
+            }
+            if (!res.ok) {
+                const body = await res.text();
+                return {
+                    content: [{ type: "text", text: `Error (${res.status}): ${body}` }],
+                    isError: true,
+                };
+            }
+            const groundingText = await res.text();
+            return {
+                content: [{ type: "text", text: groundingText }],
+            };
+        }
+        if (name === "status") {
+            const res = await fetch(`${API_BASE}/v1/status`, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+            });
+            if (!res.ok) {
+                return {
+                    content: [{ type: "text", text: `Error (${res.status}): ${await res.text()}` }],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export declare function runSetup(apiKey: string): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+function getClients() {
+    const home = os.homedir();
+    const isWin = process.platform === "win32";
+    const isMac = process.platform === "darwin";
+    const appData = process.env.APPDATA || "";
+    const clients = [];
+    // Claude Desktop
+    const claudeDesktopPath = isWin
+        ? path.join(appData, "Claude", "claude_desktop_config.json")
+        : isMac
+            ? path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+            : path.join(home, ".config", "Claude", "claude_desktop_config.json");
+    if (fs.existsSync(path.dirname(claudeDesktopPath))) {
+        clients.push({ name: "Claude Desktop", configPath: claudeDesktopPath });
+    }
+    // Claude Code
+    const claudeCodePath = path.join(home, ".claude", "settings.json");
+    if (fs.existsSync(path.dirname(claudeCodePath))) {
+        clients.push({ name: "Claude Code", configPath: claudeCodePath });
+    }
+    // Cursor
+    const cursorPath = isWin
+        ? path.join(appData, "Cursor", "User", "globalStorage", "cursor.mcp", "mcp.json")
+        : isMac
+            ? path.join(home, "Library", "Application Support", "Cursor", "User", "globalStorage", "cursor.mcp", "mcp.json")
+            : path.join(home, ".config", "Cursor", "User", "globalStorage", "cursor.mcp", "mcp.json");
+    if (fs.existsSync(path.dirname(cursorPath))) {
+        clients.push({ name: "Cursor", configPath: cursorPath });
+    }
+    return clients;
+}
+function writeConfig(configPath, apiKey) {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        }
+        catch {
+            config = {};
+        }
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== "object") {
+        config.mcpServers = {};
+    }
+    config.mcpServers.perceptia = {
+        command: "npx",
+        args: ["-y", "perceptia-mcp"],
+        env: {
+            PERCEPTIA_API_KEY: apiKey,
+        },
+    };
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+export async function runSetup(apiKey) {
+    if (!apiKey.startsWith("ck_live_")) {
+        console.error("Error: Invalid API key format. Keys start with ck_live_");
+        console.error("Get your key at https://perceptiamcp.com/dashboard");
+        process.exit(1);
+    }
+    // Validate key against API
+    console.log("Validating API key...");
+    try {
+        const res = await fetch("https://api.perceptiamcp.com/v1/status", {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (res.status === 401) {
+            console.error("Error: API key is invalid or expired.");
+            console.error("Check your keys at https://perceptiamcp.com/dashboard");
+            process.exit(1);
+        }
+        if (!res.ok) {
+            console.error(`Warning: Could not validate key (${res.status}). Continuing anyway.`);
+        }
+        else {
+            console.log("API key is valid.");
+        }
+    }
+    catch {
+        console.error("Warning: Could not reach API to validate key. Continuing anyway.");
+    }
+    const clients = getClients();
+    if (clients.length === 0) {
+        console.error("No supported AI clients found (Claude Desktop, Claude Code, Cursor).");
+        console.error("Install one of them first, then run this command again.");
+        process.exit(1);
+    }
+    console.log("");
+    console.log(`Found ${clients.length} client(s):`);
+    for (const client of clients) {
+        writeConfig(client.configPath, apiKey);
+        console.log(`  + ${client.name} — configured at ${client.configPath}`);
+    }
+    console.log("");
+    console.log("Done! Restart your AI client to activate Perceptia grounding.");
+    console.log("");
+    console.log("Usage: Ask your AI assistant anything — it now has access to the 'ground' tool.");
+    console.log("       It will automatically fetch relevant grounding context from Perceptia.");
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "perceptia-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Perceptia grounding API — one command setup for Claude, Cursor, and more",
+  "type": "module",
+  "bin": {
+    "perceptia-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "perceptia",
+    "grounding",
+    "claude",
+    "ai",
+    "context"
+  ],
+  "author": "Perceptia",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}