@agentaeo/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @agentaeo/mcp-server
+
+MCP (Model Context Protocol) server for [AgentAEO](https://agentaeo.com) — run AEO (Answer Engine Optimization) audits across ChatGPT, Perplexity, Claude, and Google AI.
+
+**Source:** [`agentaeo/agentaeo-mcp-server`](https://github.com/agentaeo/agentaeo-mcp-server) on GitHub (local folder name: `agentaeo-mcp-server`).
+
+## Installation
+
+```bash
+npm install -g @agentaeo/mcp-server
+# or
+npx @agentaeo/mcp-server
+```
+
+## Configuration
+
+Set your API key (get one at [agentaeo.com/agents](https://agentaeo.com/agents)):
+
+```bash
+export AGENTAEO_API_KEY=your_api_key_here
+```
+
+## Claude Desktop
+
+Config file on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### After publishing to npm (recommended)
+
+```json
+{
+  "mcpServers": {
+    "agentaeo": {
+      "command": "npx",
+      "args": ["-y", "@agentaeo/mcp-server"],
+      "env": {
+        "AGENTAEO_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+`-y` skips npx’s “Ok to proceed?” prompt (important for GUI-launched processes).
+
+### Local dev (before publish)
+
+**Prefer `node` + `dist/index.js`** — `npx` + a local `.tgz` often breaks in Claude Desktop (npm path bugs, “tarball corrupted”, or `Permission denied` when the shell mishandles the archive). Avoid `.tgz` in the MCP config unless you’ve verified it on your machine.
+
+1. In the repo: `npm install` and `npm run build` (must produce `dist/index.js`).
+2. Use your **real** AgentAEO key in `AGENTAEO_API_KEY` (not the literal text `your_real_key_here`).
+
+**Recommended — `node` + absolute path to `dist/index.js`:**
+
+```json
+{
+  "mcpServers": {
+    "agentaeo": {
+      "command": "node",
+      "args": ["/Users/aashishn/agents/agentaeo-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTAEO_API_KEY": "paste_your_agentaeo_live_key_here"
+      }
+    }
+  }
+}
+```
+
+If `node` is not on Claude’s PATH (e.g. only nvm), use the full path to node, e.g. `"/Users/aashishn/.nvm/versions/node/v22.16.0/bin/node"` as `command` and the same `args` for `dist/index.js`.
+
+**Optional — tarball via npx** (only if `node` works from Terminal but you prefer npx): some setups need `file:` prefix — ask in Terminal first:  
+`npx -y file:/Users/aashishn/agents/agentaeo-mcp-server/agentaeo-mcp-server-0.1.0.tgz` — if that fails, stick to `node` + `dist`.
+
+After editing the config, **fully quit Claude Desktop** (Cmd+Q) and reopen. Check **Settings → Developer → Local MCP servers** for a green status.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `run_aeo_audit` | Run an AEO audit for a URL. Free: 8 queries. Paid: 40 queries with full blueprint. |
+| `check_aeo_audit_status` | Poll audit status and retrieve results. Use the `auditId` from `run_aeo_audit`. |
+
+## Example
+
+Ask Claude: *"Run a free AEO audit for agentaeo.com with keyword 'AI search visibility'"*
+
+Then: *"Check the status of that audit"* (Claude will use the returned auditId)
+
+## Requirements
+
+- Node.js 18+
+- AgentAEO API key from [agentaeo.com/agents](https://agentaeo.com/agents)
+
+## Development & publishing
+
+Run all **npm** commands from the repo root (the folder that contains `package.json`), e.g.:
+
+```bash
+cd ~/agents/agentaeo-mcp-server   # or your path to agentaeo-mcp-server
+npm install
+npm run build
+npm pack                          # optional: test tarball before publish
+```
+
+Publish (after `npm login` and scope access for `@agentaeo`):
+
+```bash
+npm publish --access public
+```
+
+**GitHub vs npm:** The GitHub repo can stay **private**; the **npm package** `@agentaeo/mcp-server` is usually **public** so `npx @agentaeo/mcp-server` works for everyone. Those are independent settings.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * @agentaeo/mcp-server — MCP server for AgentAEO
+ * Run AEO audits across ChatGPT, Perplexity, Claude, and Google AI.
+ *
+ * Requires: AGENTAEO_API_KEY environment variable
+ * Get your key at: https://agentaeo.com/agents
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * @agentaeo/mcp-server — MCP server for AgentAEO
+ * Run AEO audits across ChatGPT, Perplexity, Claude, and Google AI.
+ *
+ * Requires: AGENTAEO_API_KEY environment variable
+ * Get your key at: https://agentaeo.com/agents
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_BASE = "https://agentaeo-api.onrender.com";
+function getApiKey() {
+    const key = process.env.AGENTAEO_API_KEY?.trim();
+    if (!key) {
+        console.error("[agentaeo-mcp-server] ERROR: AGENTAEO_API_KEY is required but not set.\n" +
+            "Get your API key at https://agentaeo.com/agents and set it:\n" +
+            "  export AGENTAEO_API_KEY=your_key_here\n" +
+            "Or add it to your Claude Desktop config: env.AGENTAEO_API_KEY");
+        process.exit(1);
+    }
+    return key;
+}
+async function main() {
+    const apiKey = getApiKey();
+    const server = new McpServer({
+        name: "agentaeo",
+        version: "0.1.0",
+    });
+    server.tool("run_aeo_audit", "Run an AEO audit for a URL. Tests visibility across ChatGPT, Perplexity, Claude, and Google AI. Free tier: 8 queries. Paid tier: 40 queries with full blueprint.", {
+        url: z.string().url().describe("The website URL to audit (e.g. https://example.com)"),
+        keyword: z.string().optional().describe("Primary industry keyword for query generation (e.g. payment API)"),
+        tier: z.enum(["free", "paid"]).optional().default("free").describe("Audit tier: free (8 queries) or paid (40 queries)"),
+    }, async ({ url, keyword, tier }) => {
+        try {
+            const res = await fetch(`${API_BASE}/api/aeo-audit`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-API-Key": apiKey,
+                },
+                body: JSON.stringify({ url, keyword: keyword || "", tier: tier || "free" }),
+            });
+            const data = (await res.json());
+            if (!res.ok) {
+                const err = data?.error || data?.message || `HTTP ${res.status}`;
+                return {
+                    content: [{ type: "text", text: `Error: ${err}` }],
+                    isError: true,
+                };
+            }
+            const auditId = (data?.auditId ?? data?.audit_id ?? data?.id);
+            const status = data?.status ?? "queued";
+            const text = auditId
+                ? `Audit started. auditId: ${auditId}\nStatus: ${status}\nUse check_aeo_audit_status with this auditId to poll for results.`
+                : JSON.stringify(data, null, 2);
+            return {
+                content: [{ type: "text", text }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("check_aeo_audit_status", "Check the status and results of an AEO audit. Poll this with the auditId returned from run_aeo_audit until status is completed.", {
+        auditId: z.string().describe("The audit ID returned from run_aeo_audit"),
+    }, async ({ auditId }) => {
+        try {
+            const res = await fetch(`${API_BASE}/api/aeo-status/${auditId}`, {
+                method: "GET",
+                headers: {
+                    "X-API-Key": apiKey,
+                },
+            });
+            const data = (await res.json());
+            if (!res.ok) {
+                const err = data?.error || data?.message || `HTTP ${res.status}`;
+                return {
+                    content: [{ type: "text", text: `Error: ${err}` }],
+                    isError: true,
+                };
+            }
+            const status = data?.status ?? (data?.current_step != null ? "processing" : "unknown");
+            const isComplete = data?.is_complete ?? (data?.status === "completed");
+            const score = data?.score;
+            const grade = data?.grade;
+            let text = `Status: ${status}\nis_complete: ${isComplete}`;
+            if (score != null)
+                text += `\nScore: ${score}`;
+            if (grade)
+                text += `\nGrade: ${grade}`;
+            if (isComplete && data?.findings) {
+                text += `\n\nFull results:\n${JSON.stringify(data, null, 2)}`;
+            }
+            else {
+                text += `\n\nRaw response:\n${JSON.stringify(data, null, 2)}`;
+            }
+            return {
+                content: [{ type: "text", text }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[agentaeo-mcp-server] Fatal:", err);
+    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/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@agentaeo/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for AgentAEO — run AEO audits across ChatGPT, Perplexity, Claude, and Google AI",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "agentaeo-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "agentaeo",
+    "aeo",
+    "answer-engine-optimization",
+    "ai-search"
+  ],
+  "author": "AIMetica Solutions LLP <agents@agentaeo.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentaeo/agentaeo-mcp-server.git"
+  },
+  "homepage": "https://agentaeo.com/agents",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}