brandguideai-mcp 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# brandguideai-mcp
+
+Brand strategy knowledge base for Claude Code, Cursor, Windsurf, and any MCP-compatible tool.
+
+Search 1,000+ pages of brand methodology, design guidelines, and expert video transcripts — directly from your development environment.
+
+## Quick start
+
+```bash
+npx brandguideai-mcp
+```
+
+No signup needed. 8 free queries included.
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add brandguide -- npx brandguideai-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "brandguide": {
+      "command": "npx",
+      "args": ["-y", "brandguideai-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / Other MCP clients
+
+Add to your MCP configuration:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "brandguideai-mcp"]
+}
+```
+
+## What you get
+
+**`search_brand_knowledge`** — one tool that searches the brandguide/AI knowledge base.
+
+Ask anything about brand strategy:
+- "What is brand identity?"
+- "How do I choose brand colors?"
+- "What makes a good brand name?"
+- "Mi a brand pozicionálás?" (works in Hungarian too)
+
+Responses include expert answers with source citations from brand strategy books and video transcripts.
+
+## Free tier
+
+Every user gets 8 free queries. No account or API key required — a temporary session is created automatically on first use.
+
+After 8 queries, the tool returns upgrade links:
+- **Creator** — 300 queries/month
+- **Pro** — 1,000 queries/month
+- **Mentor+** — unlimited
+
+## For existing brandguide/AI subscribers
+
+Your subscription quota works automatically. The MCP server uses the same account system as the web app at [ai.brandguide.hu](https://ai.brandguide.hu).
+
+## How it works
+
+The MCP server connects to the brandguide/AI knowledge base through the partner API. Queries are processed by the same RAG pipeline that powers the web app — Voyage AI embeddings, Supabase vector search, and Claude for response generation.
+
+Credentials are stored locally at `~/.brandguide/credentials.json`.
+
+## Links
+
+- [brandguide/AI web app](https://ai.brandguide.hu)
+- [Agents & MCP info](https://ai.brandguide.hu/agents)
+- [brandguide/AI Skill](https://ai.brandguide.hu/agents)
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+export declare function getAccessToken(): Promise<string>;
+export declare function getStoredEmail(): string;

package/dist/auth.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAccessToken = getAccessToken;
+exports.getStoredEmail = getStoredEmail;
+const supabase_js_1 = require("@supabase/supabase-js");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const constants_js_1 = require("./constants.js");
+const CREDENTIALS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.brandguide');
+const CREDENTIALS_FILE = (0, node_path_1.join)(CREDENTIALS_DIR, 'credentials.json');
+let cachedSession = null;
+function loadCredentials() {
+    try {
+        if (!(0, node_fs_1.existsSync)(CREDENTIALS_FILE))
+            return null;
+        const raw = (0, node_fs_1.readFileSync)(CREDENTIALS_FILE, 'utf-8');
+        const data = JSON.parse(raw);
+        if (data.email && data.password && data.userId)
+            return data;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveCredentials(creds) {
+    try {
+        if (!(0, node_fs_1.existsSync)(CREDENTIALS_DIR)) {
+            (0, node_fs_1.mkdirSync)(CREDENTIALS_DIR, { recursive: true });
+        }
+        (0, node_fs_1.writeFileSync)(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), 'utf-8');
+    }
+    catch (err) {
+        console.error('[auth] Failed to save credentials:', err);
+    }
+}
+async function createTempAccount() {
+    const response = await fetch(constants_js_1.CREATE_TEMP_SESSION_URL, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${constants_js_1.SUPABASE_ANON_KEY}`,
+            apikey: constants_js_1.SUPABASE_ANON_KEY,
+            'Content-Type': 'application/json',
+            ...constants_js_1.BOT_SHIELD_HEADERS,
+        },
+        body: JSON.stringify({
+            landingVariant: 'business',
+            uiLang: 'en',
+            sessionFingerprint: `mcp-${Date.now()}`,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Failed to create temp account: ${response.status} ${text}`);
+    }
+    const data = await response.json();
+    if (!data.email || !data.password || !data.userId) {
+        throw new Error('Invalid response from create-temp-session');
+    }
+    return { email: data.email, password: data.password, userId: data.userId };
+}
+async function signIn(email, password) {
+    const supabase = (0, supabase_js_1.createClient)(constants_js_1.SUPABASE_URL, constants_js_1.SUPABASE_ANON_KEY, {
+        auth: { persistSession: false, autoRefreshToken: false },
+    });
+    const { data, error } = await supabase.auth.signInWithPassword({ email, password });
+    if (error || !data.session) {
+        throw new Error(error?.message || 'Sign-in failed');
+    }
+    return data.session;
+}
+async function getAccessToken() {
+    // Check if cached session is still valid (5 min buffer)
+    if (cachedSession) {
+        const expiresAt = (cachedSession.expires_at ?? 0) * 1000;
+        if (expiresAt > Date.now() + 5 * 60 * 1000) {
+            return cachedSession.access_token;
+        }
+        cachedSession = null;
+    }
+    // Try stored credentials
+    let creds = loadCredentials();
+    if (!creds) {
+        // Create new temp account
+        creds = await createTempAccount();
+        saveCredentials(creds);
+    }
+    try {
+        cachedSession = await signIn(creds.email, creds.password);
+        return cachedSession.access_token;
+    }
+    catch {
+        // Credentials might be stale (account deleted), create new account
+        creds = await createTempAccount();
+        saveCredentials(creds);
+        cachedSession = await signIn(creds.email, creds.password);
+        return cachedSession.access_token;
+    }
+}
+function getStoredEmail() {
+    const creds = loadCredentials();
+    return creds?.email ?? '';
+}

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+interface Source {
+    title?: string;
+    type?: string;
+    url?: string;
+    page?: number;
+}
+interface SearchResult {
+    answer: string;
+    sources: Source[];
+    remaining: number | null;
+    total: number | null;
+    quotaExceeded: boolean;
+}
+export declare function searchBrandKnowledge(query: string): Promise<SearchResult>;
+export {};

package/dist/client.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchBrandKnowledge = searchBrandKnowledge;
+const constants_js_1 = require("./constants.js");
+const auth_js_1 = require("./auth.js");
+const PARTNER_API_URL = `${constants_js_1.SUPABASE_URL}/functions/v1/partner-api`;
+function formatSources(sources) {
+    if (!sources.length)
+        return '';
+    const lines = sources.map((s) => {
+        const parts = [s.title || 'Untitled'];
+        if (s.type)
+            parts.push(s.type.toUpperCase());
+        if (s.page)
+            parts.push(`p.${s.page}`);
+        return `- ${parts.join(' | ')}`;
+    });
+    return '\nSources:\n' + lines.join('\n');
+}
+function formatQuotaWall(email) {
+    const emailParam = email ? `?prefilled_email=${encodeURIComponent(email)}` : '';
+    return [
+        "You've used all your free brandguide/AI responses.",
+        '',
+        'Upgrade to continue:',
+        `  Creator (300/month): ${constants_js_1.STRIPE_LINKS.creator}${emailParam}`,
+        `  Pro (1,000/month): ${constants_js_1.STRIPE_LINKS.pro}${emailParam}`,
+        `  Mentor+ (unlimited): ${constants_js_1.STRIPE_LINKS.mentorPlus}${emailParam}`,
+        '',
+        'Or visit https://ai.brandguide.hu to manage your account.',
+    ].join('\n');
+}
+async function searchBrandKnowledge(query) {
+    let accessToken = await (0, auth_js_1.getAccessToken)();
+    const makeRequest = async (token) => fetch(`${PARTNER_API_URL}?apikey=${constants_js_1.SUPABASE_ANON_KEY}`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            ...constants_js_1.BOT_SHIELD_HEADERS,
+        },
+        body: JSON.stringify({ query }),
+    });
+    let response = await makeRequest(accessToken);
+    // 401 retry with fresh token
+    if (response.status === 401) {
+        accessToken = await (0, auth_js_1.getAccessToken)();
+        response = await makeRequest(accessToken);
+    }
+    // Quota exceeded
+    if (response.status === 402 || response.status === 429) {
+        const email = (0, auth_js_1.getStoredEmail)();
+        return {
+            answer: formatQuotaWall(email),
+            sources: [],
+            remaining: 0,
+            total: null,
+            quotaExceeded: true,
+        };
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`brandguide/AI API error: ${response.status} ${text.slice(0, 200)}`);
+    }
+    const data = await response.json();
+    const answer = data.answer || data.response || '';
+    const sources = Array.isArray(data.sources)
+        ? data.sources
+        : [];
+    const usage = data.usage || {};
+    return {
+        answer: answer + formatSources(sources),
+        sources,
+        remaining: typeof usage.remaining === 'number' ? usage.remaining : null,
+        total: typeof usage.limit === 'number' ? usage.limit : null,
+        quotaExceeded: false,
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,15 @@
+export declare const SUPABASE_URL = "https://udqiowvplrkdrviahylk.supabase.co";
+export declare const SUPABASE_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InVkcWlvd3ZwbHJrZHJ2aWFoeWxrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTI4MzEwNDYsImV4cCI6MjA2ODQwNzA0Nn0.GFEyIVbnl5oTKL8FnyelU04RyS5fGDvpNm3AjFqDCtQ";
+export declare const CREATE_TEMP_SESSION_URL = "https://udqiowvplrkdrviahylk.supabase.co/functions/v1/create-temp-session";
+export declare const CONVERSATIONAL_RAG_URL = "https://udqiowvplrkdrviahylk.supabase.co/functions/v1/conversational-rag";
+export declare const STRIPE_PAYMENT_LINK_ID = "5kQ8wO1xs0rS8q15NE2sM03";
+export declare const STRIPE_LINKS: {
+    creator: string;
+    pro: string;
+    mentorPlus: string;
+};
+export declare const BOT_SHIELD_HEADERS: {
+    'User-Agent': string;
+    Origin: string;
+    'Accept-Language': string;
+};

package/dist/constants.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOT_SHIELD_HEADERS = exports.STRIPE_LINKS = exports.STRIPE_PAYMENT_LINK_ID = exports.CONVERSATIONAL_RAG_URL = exports.CREATE_TEMP_SESSION_URL = exports.SUPABASE_ANON_KEY = exports.SUPABASE_URL = void 0;
+exports.SUPABASE_URL = 'https://udqiowvplrkdrviahylk.supabase.co';
+exports.SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InVkcWlvd3ZwbHJrZHJ2aWFoeWxrIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTI4MzEwNDYsImV4cCI6MjA2ODQwNzA0Nn0.GFEyIVbnl5oTKL8FnyelU04RyS5fGDvpNm3AjFqDCtQ';
+exports.CREATE_TEMP_SESSION_URL = `${exports.SUPABASE_URL}/functions/v1/create-temp-session`;
+exports.CONVERSATIONAL_RAG_URL = `${exports.SUPABASE_URL}/functions/v1/conversational-rag`;
+exports.STRIPE_PAYMENT_LINK_ID = '5kQ8wO1xs0rS8q15NE2sM03';
+exports.STRIPE_LINKS = {
+    creator: `https://buy.stripe.com/${exports.STRIPE_PAYMENT_LINK_ID}`,
+    pro: `https://buy.stripe.com/${exports.STRIPE_PAYMENT_LINK_ID}`,
+    mentorPlus: `https://buy.stripe.com/${exports.STRIPE_PAYMENT_LINK_ID}`,
+};
+exports.BOT_SHIELD_HEADERS = {
+    'User-Agent': 'Mozilla/5.0 (compatible; brandguideai-mcp/1.0)',
+    'Origin': 'https://ai.brandguide.hu',
+    'Accept-Language': 'en',
+};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const client_js_1 = require("./client.js");
+const server = new index_js_1.Server({ name: 'brandguideai-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'search_brand_knowledge',
+            description: "Search brandguide/AI's brand strategy knowledge base — 1,000+ pages of methodology, design guidelines, and expert video transcripts. Works in Hungarian and English.",
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Your brand strategy question',
+                    },
+                },
+                required: ['query'],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    if (request.params.name !== 'search_brand_knowledge') {
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
+            isError: true,
+        };
+    }
+    const query = String(request.params.arguments?.query || '').trim();
+    if (!query) {
+        return {
+            content: [{ type: 'text', text: 'Query is required.' }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await (0, client_js_1.searchBrandKnowledge)(query);
+        if (result.quotaExceeded) {
+            return {
+                content: [{ type: 'text', text: result.answer }],
+            };
+        }
+        const footer = result.remaining !== null && result.total !== null
+            ? `\n\n[${result.remaining}/${result.total} queries remaining]`
+            : '';
+        return {
+            content: [{ type: 'text', text: result.answer + footer }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "brandguideai-mcp",
+  "version": "1.0.0",
+  "description": "brandguide/AI MCP server — brand strategy knowledge base for Claude Code, Cursor, and any MCP client",
+  "main": "dist/index.js",
+  "bin": {
+    "brandguideai-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": ["mcp", "brand", "branding", "ai", "claude", "brandguide"],
+  "files": ["dist", "README.md"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "@supabase/supabase-js": "^2.39.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}