mcp-server-peecai 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Hein
+
+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,271 @@
+<p align="center">
+  <h1 align="center">Peec.ai MCP Server</h1>
+  <p align="center">
+    Community-built MCP server for the <a href="https://peec.ai">Peec.ai</a> API — AI Search Analytics for brand visibility, sentiment, and citations across ChatGPT, Perplexity, and other AI models.
+  </p>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node.js >= 22">
+  <img src="https://img.shields.io/badge/MCP-compatible-0098FF?style=flat-square" alt="MCP compatible">
+</p>
+
+> **Note:** This is an unofficial community project, not affiliated with or endorsed by Peec.ai. It requires a [Peec.ai](https://peec.ai) account and API key.
+
+> **API Beta:** The Peec.ai API is currently in beta — endpoints, payloads, and responses may change. Access is limited to Enterprise customers.
+
+---
+
+## What it does
+
+Peec.ai tracks how brands appear in AI-generated answers. This MCP server gives Claude direct access to that data — 11 tools covering projects, brands, prompts, chats, and analytics reports.
+
+**Key capabilities:**
+- Query brand visibility, sentiment, and position across AI models
+- Analyze which domains and URLs get cited in AI responses
+- Inspect individual chat interactions with full source attribution
+- Slice data by model, prompt, category tag, or topic
+
+## Quick Start
+
+### 1. Get your API key
+
+Sign up at [app.peec.ai](https://app.peec.ai) and create an API key under **Settings > API Keys**.
+
+### 2. Install
+
+```bash
+git clone https://github.com/thein-art/mcp-server-peecai.git
+cd mcp-server-peecai
+npm install && npm run build
+```
+
+### 3. Configure
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+The repository includes a `.mcp.json` for automatic setup. Set the environment variables and Claude Code will pick it up:
+
+```bash
+export PEECAI_API_KEY="your-api-key"
+export PEECAI_PROJECT_ID="your-project-id"  # optional default
+```
+
+Or add manually:
+
+```bash
+claude mcp add --transport stdio peecai -- node /path/to/mcp-server-peecai/dist/index.js
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "peecai": {
+      "command": "node",
+      "args": ["/path/to/mcp-server-peecai/dist/index.js"],
+      "env": {
+        "PEECAI_API_KEY": "your-api-key",
+        "PEECAI_PROJECT_ID": "your-project-id"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code / Cursor</strong></summary>
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "peecai": {
+      "command": "node",
+      "args": ["/path/to/mcp-server-peecai/dist/index.js"],
+      "env": {
+        "PEECAI_API_KEY": "your-api-key",
+        "PEECAI_PROJECT_ID": "your-project-id"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+### 4. Verify
+
+In Claude Code, run `/mcp` to confirm the `peecai` server is connected.
+
+## Tools
+
+### Data Retrieval
+
+**`list_projects`** — List all projects for the company.
+- Returns: project IDs, names, statuses (`CUSTOMER` = active, `PITCH_ENDED` = completed)
+- Parameters: `limit`, `offset`
+
+**`list_brands`** — List tracked brands with their associated domains.
+- Parameters: `project_id`, `limit`, `offset`
+
+**`list_prompts`** — List monitored search prompts.
+- Returns: prompt messages, tags, topics, user location, search volume
+- Parameters: `project_id`, `limit`, `offset`
+
+**`list_tags`** — List category tags for a project.
+- Parameters: `project_id`, `limit`, `offset`
+
+**`list_topics`** — List topic groupings for a project.
+- Parameters: `project_id`, `limit`, `offset`
+
+**`list_models`** — List tracked AI models (ChatGPT, Perplexity, etc.).
+- Returns: model IDs and active status
+- Parameters: `project_id`, `limit`, `offset`
+
+**`list_chats`** — List AI chat interactions with optional date filtering.
+- Returns: chat IDs, prompt/model refs, dates
+- Parameters: `project_id`, `start_date`, `end_date`, `limit`, `offset`
+
+**`get_chat_content`** — Get full content of a specific chat.
+- Returns: sources (URLs, domains, citation counts), brands mentioned, messages, queries, products
+- Parameters: `chat_id`, `project_id`
+
+### Analytics Reports
+
+All report tools support `dimensions` for multi-level breakdowns: `prompt_id`, `model_id`, `tag_id`, `topic_id`. Date filtering via `start_date` / `end_date` (YYYY-MM-DD). All report tools also accept a `filters` parameter for server-side filtering (`field`, `operator: "in" | "not_in"`, `values`). Convenience shortcuts `brand_id` / `classification` remain available.
+
+**`get_brands_report`** — Brand analytics per brand.
+
+| Metric | Description |
+|--------|-------------|
+| `visibility` | Ratio 0–1 (visibility_count / visibility_total) |
+| `sentiment` | Score 0–100, 50 = neutral |
+| `position` | Average rank when mentioned, lower = better |
+| `share_of_voice` | Share of voice 0–1 (proportion of total mentions) |
+| `mention_count` | Number of times the brand was mentioned |
+
+**`get_domains_report`** — Domain-level analytics.
+
+| Metric | Description |
+|--------|-------------|
+| `usage_rate` | Share of chats citing this domain (0–1) |
+| `citation_avg` | Average citations per chat |
+| `classification` | `OWN`, `CORPORATE`, `COMPETITOR`, `EDITORIAL`, `REFERENCE`, `INSTITUTIONAL`, `UGC`, `OTHER` |
+
+**`get_urls_report`** — URL-level analytics.
+
+| Metric | Description |
+|--------|-------------|
+| `usage_count` | Number of chats citing this URL |
+| `citation_count` | Total citations across all chats |
+| `citation_avg` | Average citations per chat |
+| `classification` | `HOMEPAGE`, `PRODUCT_PAGE`, `CATEGORY_PAGE`, `LISTICLE`, `COMPARISON`, `ARTICLE`, `HOW_TO_GUIDE`, `PROFILE`, `ALTERNATIVE`, `DISCUSSION`, `OTHER` |
+
+### Tool Annotations
+
+| Tool | Read-only | Idempotent | Destructive |
+|------|:---------:|:----------:|:-----------:|
+| All 11 tools | Yes | Yes | No |
+
+All tools are read-only GET/POST queries against the Peec.ai API. No data is modified.
+
+## Example Prompts
+
+```
+"List my Peec.ai projects"
+"Show brand visibility for the last 30 days"
+"Which domains get cited most in AI search results?"
+"Compare brand sentiment across ChatGPT and Perplexity"
+"Show me the full chat content for chat ID abc-123"
+"Get URL report broken down by AI model"
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|:--------:|-------------|
+| `PEECAI_API_KEY` | Yes | API key from [app.peec.ai](https://app.peec.ai/api-keys) |
+| `PEECAI_PROJECT_ID` | No | Default project ID — saves repeating it in every tool call |
+
+## API Drift Detection
+
+The Peec.ai API is in beta and may change. A drift detection script compares the live OpenAPI spec against a committed snapshot:
+
+```bash
+npm run check:api-drift
+```
+
+- **No drift**: exit code 0, snapshot is current
+- **Drift detected**: exit code 1, shows a diff of changes
+
+When drift is detected:
+1. Review the diff to understand what changed
+2. Update the snapshot: `curl -s https://api.peec.ai/customer/v1/openapi/json -o api-spec/openapi-snapshot.json`
+3. Update `src/types.ts` and tools as needed
+4. Run tests to verify
+
+No API key is required — the OpenAPI spec is publicly accessible.
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 22
+- npm
+
+### Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript to dist/
+npm run dev          # Watch mode — recompile on changes
+npm test             # Run tests
+npm run test:watch   # Run tests in watch mode
+npm run check:api-drift  # Check for API spec changes
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts          # Server entry point, tool registration
+├── api-client.ts     # HTTP client for Peec.ai Customer API
+├── types.ts          # TypeScript interfaces for API responses
+├── util.ts           # Shared validation, date handling, MCP response helpers
+├── prompts.ts        # MCP prompt templates (guided workflows)
+└── tools/            # One file per MCP tool
+    ├── projects.ts
+    ├── brands.ts
+    ├── prompts.ts
+    ├── tags.ts
+    ├── topics.ts
+    ├── models.ts
+    ├── chats.ts
+    ├── chat-content.ts
+    ├── report-brands.ts
+    ├── report-domains.ts
+    └── report-urls.ts
+scripts/              # Development and CI scripts
+└── check-api-drift.sh
+api-spec/             # API specification snapshots
+└── openapi-snapshot.json
+```
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+Built by [Tobias Hein](https://github.com/thein-art) at [artaxo](https://artaxo.com) — a digital marketing agency specializing in AI Search Optimization.

package/dist/api-client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * HTTP client for the Peec.ai Customer API.
+ * Handles authentication, query parameters, timeouts, and error formatting.
+ */
+export declare class PeecApiClient {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    /** GET request that unwraps the `{ data: T }` envelope. Use for list/paginated endpoints. */
+    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    /** GET request that returns the response body directly. Use for endpoints without a `data` envelope (e.g. chat content). */
+    getRaw<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    /** POST request that unwraps the `{ data: T }` envelope. Use for analytics report endpoints. */
+    post<T>(path: string, body: Record<string, unknown>, params?: Record<string, string | undefined>): Promise<T>;
+    private request;
+    /**
+     * Builds a human-readable error message from a failed API response.
+     * Tries to extract a structured message from JSON; falls back to raw text.
+     * Truncates to MAX_ERROR_LENGTH to prevent leaking large error payloads.
+     */
+    private formatError;
+}

package/dist/api-client.js

@@ -0,0 +1,83 @@
+const BASE_URL = "https://api.peec.ai/customer/v1";
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_ERROR_LENGTH = 500;
+/**
+ * HTTP client for the Peec.ai Customer API.
+ * Handles authentication, query parameters, timeouts, and error formatting.
+ */
+export class PeecApiClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /** GET request that unwraps the `{ data: T }` envelope. Use for list/paginated endpoints. */
+    async get(path, params) {
+        const response = await this.request(path, { method: "GET", params });
+        const json = await response.json();
+        return json.data;
+    }
+    /** GET request that returns the response body directly. Use for endpoints without a `data` envelope (e.g. chat content). */
+    async getRaw(path, params) {
+        const response = await this.request(path, { method: "GET", params });
+        return response.json();
+    }
+    /** POST request that unwraps the `{ data: T }` envelope. Use for analytics report endpoints. */
+    async post(path, body, params) {
+        const response = await this.request(path, {
+            method: "POST",
+            params,
+            body: JSON.stringify(body),
+            extraHeaders: { "Content-Type": "application/json" },
+        });
+        const json = await response.json();
+        return json.data;
+    }
+    async request(path, options) {
+        const url = new URL(`${BASE_URL}${path}`);
+        if (options.params) {
+            for (const [key, value] of Object.entries(options.params)) {
+                if (value !== undefined && value !== null && value !== "") {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const response = await fetch(url.toString(), {
+            method: options.method,
+            headers: {
+                "X-API-Key": this.apiKey,
+                "Accept": "application/json",
+                ...options.extraHeaders,
+            },
+            body: options.body,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new Error(await this.formatError(response));
+        }
+        return response;
+    }
+    /**
+     * Builds a human-readable error message from a failed API response.
+     * Tries to extract a structured message from JSON; falls back to raw text.
+     * Truncates to MAX_ERROR_LENGTH to prevent leaking large error payloads.
+     */
+    async formatError(response) {
+        const text = await response.text();
+        let message;
+        try {
+            const json = JSON.parse(text);
+            message = json.message || json.error || text;
+        }
+        catch {
+            message = text;
+        }
+        if (typeof message !== "string") {
+            message = JSON.stringify(message);
+        }
+        if (message.length > MAX_ERROR_LENGTH) {
+            message = message.slice(0, MAX_ERROR_LENGTH) + "…";
+        }
+        return `Peec API error ${response.status}: ${message}`;
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Peec.ai MCP Server
+ *
+ * Exposes the Peec.ai Customer API as MCP tools for AI Search Analytics —
+ * brand visibility, sentiment, citations, and domain/URL analysis across
+ * AI models like ChatGPT and Perplexity.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Peec.ai MCP Server
+ *
+ * Exposes the Peec.ai Customer API as MCP tools for AI Search Analytics —
+ * brand visibility, sentiment, citations, and domain/URL analysis across
+ * AI models like ChatGPT and Perplexity.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { PeecApiClient } from "./api-client.js";
+import { registerProjectsTool } from "./tools/projects.js";
+import { registerBrandsTool } from "./tools/brands.js";
+import { registerPromptsTool } from "./tools/prompts.js";
+import { registerTagsTool } from "./tools/tags.js";
+import { registerTopicsTool } from "./tools/topics.js";
+import { registerModelsTool } from "./tools/models.js";
+import { registerChatsTool } from "./tools/chats.js";
+import { registerChatContentTool } from "./tools/chat-content.js";
+import { registerBrandsReportTool } from "./tools/report-brands.js";
+import { registerDomainsReportTool } from "./tools/report-domains.js";
+import { registerUrlsReportTool } from "./tools/report-urls.js";
+import { registerPromptTemplates } from "./prompts.js";
+const apiKey = process.env.PEECAI_API_KEY;
+if (!apiKey) {
+    console.error("PEECAI_API_KEY environment variable is required");
+    process.exit(1);
+}
+const client = new PeecApiClient(apiKey);
+const server = new McpServer({
+    name: "peecai",
+    version: "0.2.0",
+});
+// Register tools
+registerProjectsTool(server, client);
+registerBrandsTool(server, client);
+registerPromptsTool(server, client);
+registerTagsTool(server, client);
+registerTopicsTool(server, client);
+registerModelsTool(server, client);
+registerChatsTool(server, client);
+registerChatContentTool(server, client);
+registerBrandsReportTool(server, client);
+registerDomainsReportTool(server, client);
+registerUrlsReportTool(server, client);
+// Register MCP prompts (guided workflows)
+registerPromptTemplates(server);
+// Register resource: projects://list
+server.resource("projects-list", "projects://list", {
+    description: "List all available Peec.ai projects for the authenticated account.",
+    mimeType: "application/json",
+}, async () => {
+    const projects = await client.get("/projects", { limit: 1000 });
+    return {
+        contents: [{
+                uri: "projects://list",
+                mimeType: "application/json",
+                text: JSON.stringify(projects),
+            }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Peec.ai MCP server running on stdio");
+    // Graceful shutdown
+    const shutdown = async () => {
+        console.error("Shutting down Peec.ai MCP server…");
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((e) => {
+    console.error("Fatal error:", e);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/prompts.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Registers guided workflow prompts for common Peec.ai analytics tasks. */
+export declare function registerPromptTemplates(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,100 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+/** Registers guided workflow prompts for common Peec.ai analytics tasks. */
+export function registerPromptTemplates(server) {
+    server.prompt("brand-visibility-analysis", "Analyze brand visibility, sentiment, and position across AI models for a project.", {
+        project_id: z.string().describe("Project ID (uses PEECAI_PROJECT_ID env if omitted)").optional(),
+        period: z.enum(["7d", "28d", "90d"]).default("28d").describe("Analysis period"),
+    }, ({ project_id, period }) => {
+        const days = { "7d": 7, "28d": 28, "90d": 90 }[period];
+        const endDate = new Date().toISOString().slice(0, 10);
+        const startDate = new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+        const projectClause = project_id ? ` for project ${project_id}` : "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Perform a brand visibility analysis${projectClause} for the period ${startDate} to ${endDate}.`,
+                            "",
+                            "Steps:",
+                            `1. Use get_brands_report with start_date="${startDate}", end_date="${endDate}" to get overall brand metrics.`,
+                            `2. Use get_brands_report with dimensions=["model_id"] to break down visibility by AI model.`,
+                            "3. Use list_brands and list_models to resolve IDs to names.",
+                            "",
+                            "Provide:",
+                            "- A summary table of all brands with visibility, sentiment, and position",
+                            "- Per-model breakdown highlighting where each brand performs best/worst",
+                            "- Key insights and recommendations for improving AI visibility",
+                        ].join("\n"),
+                    },
+                }],
+        };
+    });
+    server.prompt("competitive-gap-analysis", "Compare own brand vs competitors — identify visibility gaps across prompts and models.", {
+        project_id: z.string().describe("Project ID (uses PEECAI_PROJECT_ID env if omitted)").optional(),
+        period: z.enum(["7d", "28d", "90d"]).default("28d").describe("Analysis period"),
+    }, ({ project_id, period }) => {
+        const days = { "7d": 7, "28d": 28, "90d": 90 }[period];
+        const endDate = new Date().toISOString().slice(0, 10);
+        const startDate = new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+        const projectClause = project_id ? ` for project ${project_id}` : "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Perform a competitive gap analysis${projectClause} for the period ${startDate} to ${endDate}.`,
+                            "",
+                            "Steps:",
+                            "1. Use list_brands to identify own brand vs competitor brands.",
+                            `2. Use get_brands_report with dimensions=["prompt_id"] to see per-prompt visibility.`,
+                            `3. Use get_brands_report with dimensions=["model_id"] to see per-model visibility.`,
+                            "4. Use list_prompts to resolve prompt IDs to actual search queries.",
+                            "",
+                            "Provide:",
+                            "- Side-by-side comparison table: own brand vs each competitor",
+                            "- Top prompts where competitors outperform the own brand (visibility gaps)",
+                            "- Models where the own brand underperforms relative to competitors",
+                            "- Actionable recommendations to close the top gaps",
+                        ].join("\n"),
+                    },
+                }],
+        };
+    });
+    server.prompt("ai-search-citation-report", "Analyze which URLs and domains get cited in AI responses — find content optimization opportunities.", {
+        project_id: z.string().describe("Project ID (uses PEECAI_PROJECT_ID env if omitted)").optional(),
+        period: z.enum(["7d", "28d", "90d"]).default("28d").describe("Analysis period"),
+    }, ({ project_id, period }) => {
+        const days = { "7d": 7, "28d": 28, "90d": 90 }[period];
+        const endDate = new Date().toISOString().slice(0, 10);
+        const startDate = new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+        const projectClause = project_id ? ` for project ${project_id}` : "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Generate an AI search citation report${projectClause} for the period ${startDate} to ${endDate}.`,
+                            "",
+                            "Steps:",
+                            `1. Use get_domains_report with start_date="${startDate}", end_date="${endDate}" to see top cited domains.`,
+                            "2. Use get_domains_report with classification filter to compare OWN vs EDITORIAL vs COMPETITOR domains.",
+                            `3. Use get_urls_report with start_date="${startDate}", end_date="${endDate}" to find top cited URLs.`,
+                            "4. Use get_urls_report with classification filter for ARTICLE and HOW_TO_GUIDE to find editorial opportunities.",
+                            "",
+                            "Provide:",
+                            "- Top 20 most-cited domains with classification and usage rate",
+                            "- Own domain performance vs editorial and competitor domains",
+                            "- Top 20 most-cited URLs with titles and citation counts",
+                            "- Content recommendations: which types of pages get cited most, and what the brand should create",
+                        ].join("\n"),
+                    },
+                }],
+        };
+    });
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4EAA4E;AAC5E,MAAM,UAAU,uBAAuB,CAAC,MAAiB;IACvD,MAAM,CAAC,MAAM,CACX,2BAA2B,EAC3B,mFAAmF,EACnF;QACE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC,CAAC,QAAQ,EAAE;QAChG,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;KAChF,EACD,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtF,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAErE,OAAO;YACL,QAAQ,EAAE,CAAC;oBACT,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,sCAAsC,aAAa,mBAAmB,SAAS,OAAO,OAAO,GAAG;4BAChG,EAAE;4BACF,QAAQ;4BACR,6CAA6C,SAAS,gBAAgB,OAAO,iCAAiC;4BAC9G,6FAA6F;4BAC7F,6DAA6D;4BAC7D,EAAE;4BACF,UAAU;4BACV,0EAA0E;4BAC1E,yEAAyE;4BACzE,gEAAgE;yBACjE,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb;iBACF,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,MAAM,CACX,0BAA0B,EAC1B,wFAAwF,EACxF;QACE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC,CAAC,QAAQ,EAAE;QAChG,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;KAChF,EACD,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtF,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAErE,OAAO;YACL,QAAQ,EAAE,CAAC;oBACT,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,qCAAqC,aAAa,mBAAmB,SAAS,OAAO,OAAO,GAAG;4BAC/F,EAAE;4BACF,QAAQ;4BACR,gEAAgE;4BAChE,sFAAsF;4BACtF,oFAAoF;4BACpF,qEAAqE;4BACrE,EAAE;4BACF,UAAU;4BACV,+DAA+D;4BAC/D,4EAA4E;4BAC5E,oEAAoE;4BACpE,oDAAoD;yBACrD,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb;iBACF,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,MAAM,CACX,2BAA2B,EAC3B,qGAAqG,EACrG;QACE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC,CAAC,QAAQ,EAAE;QAChG,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;KAChF,EACD,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtF,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAErE,OAAO;YACL,QAAQ,EAAE,CAAC;oBACT,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,wCAAwC,aAAa,mBAAmB,SAAS,OAAO,OAAO,GAAG;4BAClG,EAAE;4BACF,QAAQ;4BACR,8CAA8C,SAAS,gBAAgB,OAAO,6BAA6B;4BAC3G,yGAAyG;4BACzG,2CAA2C,SAAS,gBAAgB,OAAO,2BAA2B;4BACtG,iHAAiH;4BACjH,EAAE;4BACF,UAAU;4BACV,gEAAgE;4BAChE,8DAA8D;4BAC9D,0DAA0D;4BAC1D,kGAAkG;yBACnG,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb;iBACF,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/brands.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PeecApiClient } from "../api-client.js";
+/** Registers the list_brands tool for retrieving tracked brands and their domains. */
+export declare function registerBrandsTool(server: McpServer, client: PeecApiClient): void;

package/dist/tools/brands.js

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { PeecApiClient } from "../api-client.js";
+import { requireProjectId, summaryForList, toolResult, toolError } from "../util.js";
+/** Registers the list_brands tool for retrieving tracked brands and their domains. */
+export function registerBrandsTool(server, client) {
+    server.tool("list_brands", "List tracked brands for a Peec.ai project. Returns brand IDs, names, and associated domains.", {
+        project_id: z.string().describe("Project ID (uses PEECAI_PROJECT_ID env if omitted). Call list_projects to find IDs.").optional(),
+        limit: z.number().min(1).max(10000).default(1000).describe("Max results (1-10000)").optional(),
+        offset: z.number().min(0).default(0).describe("Results to skip").optional(),
+    }, async ({ project_id, limit, offset }) => {
+        try {
+            const data = await client.get("/brands", {
+                project_id: requireProjectId(project_id),
+                limit,
+                offset,
+            });
+            return toolResult({ _summary: summaryForList("brands", data), brands: data });
+        }
+        catch (e) {
+            return toolError(e);
+        }
+    });
+}
+//# sourceMappingURL=brands.js.map

package/dist/tools/brands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brands.js","sourceRoot":"","sources":["../../src/tools/brands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGrF,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,MAAqB;IACzE,MAAM,CAAC,IAAI,CACT,aAAa,EACb,8FAA8F,EAC9F;QACE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qFAAqF,CAAC,CAAC,QAAQ,EAAE;QACjI,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC,QAAQ,EAAE;QAC9F,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE;KAC5E,EACD,KAAK,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;QACtC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAU,SAAS,EAAE;gBAChD,UAAU,EAAE,gBAAgB,CAAC,UAAU,CAAC;gBACxC,KAAK;gBACL,MAAM;aACP,CAAC,CAAC;YACH,OAAO,UAAU,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAChF,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/chat-content.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PeecApiClient } from "../api-client.js";
+/** Registers the get_chat_content tool for retrieving full chat details. */
+export declare function registerChatContentTool(server: McpServer, client: PeecApiClient): void;