@silverbackbase/canopee 0.1.0

package/dist/auth.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+const VALIDATE_URL = process.env.SILVERBACKBASE_URL
+    ? `${process.env.SILVERBACKBASE_URL}/api/tokens/validate`
+    : null;
+const SHARED_SECRET = process.env.TRAIL_VALIDATE_SECRET ?? "";
+const cache = new Map();
+async function validateToken(token) {
+    if (VALIDATE_URL) {
+        const hash = createHash("sha256").update(token).digest("hex");
+        const cached = cache.get(hash);
+        if (cached && cached.expires > Date.now())
+            return cached.valid;
+        try {
+            const res = await fetch(VALIDATE_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "x-trail-secret": SHARED_SECRET },
+                body: JSON.stringify({ hash }),
+            });
+            const data = await res.json();
+            cache.set(hash, { valid: data.valid, expires: Date.now() + 60_000 });
+            return data.valid;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Self-host / dev: no auth
+    return true;
+}
+export const requireAuth = async (c, next) => {
+    const auth = c.req.header("authorization");
+    if (!auth?.startsWith("Bearer ")) {
+        return c.json({ error: "Unauthorized — provide Authorization: Bearer <token>" }, 401);
+    }
+    const token = auth.slice(7).trim();
+    const valid = await validateToken(token);
+    if (!valid)
+        return c.json({ error: "Invalid or revoked token" }, 401);
+    await next();
+};

package/dist/clustering.js

@@ -0,0 +1,95 @@
+import OpenAI from 'openai';
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+async function getEmbeddings(texts) {
+    const BATCH = 100;
+    const results = [];
+    for (let i = 0; i < texts.length; i += BATCH) {
+        const batch = texts.slice(i, i + BATCH);
+        const res = await openai.embeddings.create({ model: 'text-embedding-3-small', input: batch });
+        results.push(...res.data.map(d => d.embedding));
+    }
+    return results;
+}
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
+}
+function kmeans(embeddings, k, iterations = 20) {
+    const n = embeddings.length;
+    const dim = embeddings[0].length;
+    // Init centroids with random sample
+    const centroidIdx = Array.from({ length: k }, (_, i) => Math.floor((i * n) / k));
+    let centroids = centroidIdx.map(i => [...embeddings[i]]);
+    let assignments = new Array(n).fill(0);
+    for (let iter = 0; iter < iterations; iter++) {
+        // Assign
+        for (let i = 0; i < n; i++) {
+            let best = 0, bestSim = -Infinity;
+            for (let c = 0; c < k; c++) {
+                const sim = cosine(embeddings[i], centroids[c]);
+                if (sim > bestSim) {
+                    bestSim = sim;
+                    best = c;
+                }
+            }
+            assignments[i] = best;
+        }
+        // Update centroids
+        const sums = Array.from({ length: k }, () => new Array(dim).fill(0));
+        const counts = new Array(k).fill(0);
+        for (let i = 0; i < n; i++) {
+            const c = assignments[i];
+            for (let d = 0; d < dim; d++)
+                sums[c][d] += embeddings[i][d];
+            counts[c]++;
+        }
+        for (let c = 0; c < k; c++) {
+            if (counts[c] > 0)
+                centroids[c] = sums[c].map(v => v / counts[c]);
+        }
+    }
+    return assignments;
+}
+function nameTerritory(keywords) {
+    // Pick the shortest/most representative keyword as territory name
+    return keywords.slice(0, 20).sort((a, b) => a.length - b.length)[0] ?? keywords[0];
+}
+export async function clusterKeywords(keywords) {
+    if (keywords.length === 0)
+        return [];
+    const texts = keywords.map(k => k.keyword);
+    const embeddings = await getEmbeddings(texts);
+    // k = sqrt(n/2) capped between 5 and 30
+    const k = Math.min(30, Math.max(5, Math.round(Math.sqrt(keywords.length / 2))));
+    const assignments = kmeans(embeddings, k);
+    const groups = new Map();
+    for (let i = 0; i < keywords.length; i++) {
+        const c = assignments[i];
+        if (!groups.has(c))
+            groups.set(c, { keywords: [], embeddings: [] });
+        groups.get(c).keywords.push(keywords[i]);
+        groups.get(c).embeddings.push(embeddings[i]);
+    }
+    const territories = [];
+    for (const [c, group] of groups) {
+        if (group.keywords.length === 0)
+            continue;
+        const id = `t_${c}_${Date.now()}`;
+        const name = nameTerritory(group.keywords.map(k => k.keyword));
+        territories.push({
+            id,
+            name,
+            keywords: group.keywords.map((kw, i) => ({
+                ...kw,
+                territoryId: id,
+                embedding: group.embeddings[i],
+            })),
+        });
+    }
+    return territories;
+}

package/dist/dataforseo.js

@@ -0,0 +1,39 @@
+const BASE_URL = 'https://api.dataforseo.com/v3';
+function authHeader() {
+    const login = process.env.DATAFORSEO_LOGIN;
+    const password = process.env.DATAFORSEO_PASSWORD;
+    if (!login || !password)
+        throw new Error('DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD not set');
+    return 'Basic ' + Buffer.from(`${login}:${password}`).toString('base64');
+}
+async function post(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: 'POST',
+        headers: { 'Authorization': authHeader(), 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`DataForSEO ${path} → ${res.status}`);
+    return res.json();
+}
+export async function getRankedKeywords(domain, limit = 500) {
+    const data = await post('/dataforseo_labs/google/ranked_keywords/live', [{
+            target: domain,
+            language_code: 'fr',
+            location_code: 2250,
+            limit,
+            order_by: ['keyword_data.keyword_info.search_volume,desc'],
+        }]);
+    const items = data?.tasks?.[0]?.result?.[0]?.items ?? [];
+    return items
+        .map((item) => ({
+        keyword: item.keyword_data?.keyword ?? '',
+        volume: item.keyword_data?.keyword_info?.search_volume ?? 0,
+        difficulty: item.keyword_data?.keyword_properties?.keyword_difficulty ?? 0,
+        position: item.ranked_serp_element?.serp_item?.rank_absolute ?? 0,
+        domain,
+        categories: item.keyword_data?.keyword_info?.categories ?? [],
+        intent: item.keyword_data?.search_intent_info?.main_intent ?? 'informational',
+    }))
+        .filter((k) => k.keyword && k.volume > 0);
+}

package/dist/db.js

@@ -0,0 +1,44 @@
+import { DatabaseSync } from 'node:sqlite';
+const DB_PATH = process.env.DB_PATH ?? '/data/canopee.db';
+let _db = null;
+export function getDb() {
+    if (!_db) {
+        _db = new DatabaseSync(DB_PATH);
+        init(_db);
+    }
+    return _db;
+}
+function init(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS maps (
+      id TEXT PRIMARY KEY,
+      domain TEXT NOT NULL,
+      competitors TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      refreshed_at INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS territories (
+      id TEXT PRIMARY KEY,
+      map_id TEXT NOT NULL,
+      name TEXT NOT NULL,
+      category_id INTEGER NOT NULL DEFAULT 0,
+      keywords_count INTEGER NOT NULL DEFAULT 0,
+      FOREIGN KEY (map_id) REFERENCES maps(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS keywords (
+      id TEXT PRIMARY KEY,
+      territory_id TEXT NOT NULL,
+      map_id TEXT NOT NULL,
+      keyword TEXT NOT NULL,
+      volume INTEGER,
+      difficulty INTEGER,
+      domain TEXT NOT NULL,
+      position INTEGER,
+      intent TEXT,
+      FOREIGN KEY (territory_id) REFERENCES territories(id),
+      FOREIGN KEY (map_id) REFERENCES maps(id)
+    );
+  `);
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { createMcpHandler } from './mcp.js';
+import { requireAuth } from './auth.js';
+const port = parseInt(process.env.PORT ?? '3000');
+const app = new Hono();
+app.use('*', cors({ origin: '*', allowMethods: ['GET', 'POST', 'OPTIONS'] }));
+app.all('/mcp', requireAuth, createMcpHandler());
+app.get('/health', (c) => c.json({ status: 'ok', service: 'canopee' }));
+serve({ fetch: app.fetch, port }, () => {
+    const base = process.env.CANOPEE_URL ?? `http://localhost:${port}`;
+    console.log(`Canopee running on port ${port}`);
+    console.log(`  MCP → ${base}/mcp`);
+});

package/dist/mcp-stdio.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./mcp.js";
+const server = buildServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/mcp.js

@@ -0,0 +1,69 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { z } from 'zod';
+import { createMap } from './tools/create_map.js';
+import { getTerritories } from './tools/get_territories.js';
+import { getGaps } from './tools/get_gaps.js';
+import { getKeywords } from './tools/get_keywords.js';
+import { refreshMap } from './tools/refresh.js';
+export function buildServer() {
+    const server = new McpServer({ name: 'canopee', version: '0.1.0' });
+    server.registerTool('canopee_create_map', {
+        description: 'Build a semantic territory map for a domain and its competitors. Fetches ranked keywords via DataForSEO, clusters them into semantic territories, and persists the map. Returns a map_id for subsequent calls.',
+        inputSchema: {
+            domain: z.string().describe('Your domain (e.g. monsite.fr)'),
+            competitors: z.array(z.string()).describe('List of competitor domains'),
+        },
+    }, async ({ domain, competitors }) => {
+        const result = await createMap(domain, competitors);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.registerTool('canopee_get_territories', {
+        description: 'Return all semantic territories of a map with ownership scores — who dominates each territory and by how much.',
+        inputSchema: {
+            map_id: z.string().describe('Map ID returned by canopee_create_map'),
+        },
+    }, async ({ map_id }) => {
+        const result = getTerritories(map_id);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.registerTool('canopee_get_gaps', {
+        description: 'Return top content opportunities — unclaimed or weakly contested territories ranked by gap score and volume/difficulty ratio.',
+        inputSchema: {
+            map_id: z.string().describe('Map ID returned by canopee_create_map'),
+            limit: z.number().int().min(1).max(50).default(10).describe('Max number of gaps to return'),
+        },
+    }, async ({ map_id, limit }) => {
+        const result = getGaps(map_id, limit);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.registerTool('canopee_get_keywords', {
+        description: 'Return keywords for a specific territory sorted by opportunity score (volume / difficulty). Use after canopee_get_gaps to drill into a territory.',
+        inputSchema: {
+            map_id: z.string().describe('Map ID'),
+            territory_id: z.string().describe('Territory ID from canopee_get_territories or canopee_get_gaps'),
+            limit: z.number().int().min(1).max(100).default(20).describe('Max keywords to return'),
+        },
+    }, async ({ map_id, territory_id, limit }) => {
+        const result = getKeywords(map_id, territory_id, limit);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.registerTool('canopee_refresh', {
+        description: 'Refresh an existing map with fresh DataForSEO data. Re-clusters territories and returns drift (territory count delta vs previous map).',
+        inputSchema: {
+            map_id: z.string().describe('Map ID to refresh'),
+        },
+    }, async ({ map_id }) => {
+        const result = await refreshMap(map_id);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    return server;
+}
+export function createMcpHandler() {
+    return async (c) => {
+        const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        const server = buildServer();
+        await server.connect(transport);
+        return transport.handleRequest(c.req.raw);
+    };
+}

package/dist/tools/create_map.js

@@ -0,0 +1,50 @@
+import { randomUUID } from 'node:crypto';
+import { getDb } from '../db.js';
+import { getRankedKeywords } from '../dataforseo.js';
+function groupByCategory(keywords) {
+    const groups = new Map();
+    for (const kw of keywords) {
+        const cat = kw.categories[0] ?? 0;
+        if (!groups.has(cat))
+            groups.set(cat, []);
+        groups.get(cat).push(kw);
+    }
+    return groups;
+}
+function territoryName(keywords) {
+    // Most representative = highest volume keyword in the group
+    return keywords.sort((a, b) => b.volume - a.volume)[0]?.keyword ?? 'uncategorized';
+}
+export async function createMap(domain, competitors) {
+    const allDomains = [domain, ...competitors];
+    const results = await Promise.all(allDomains.map(d => getRankedKeywords(d)));
+    const allKeywords = results.flat();
+    if (allKeywords.length === 0)
+        throw new Error('No keywords found for these domains');
+    const groups = groupByCategory(allKeywords);
+    const db = getDb();
+    const mapId = randomUUID();
+    const now = Date.now();
+    db.prepare(`INSERT INTO maps (id, domain, competitors, created_at) VALUES (?, ?, ?, ?)`)
+        .run(mapId, domain, JSON.stringify(competitors), now);
+    for (const [categoryId, keywords] of groups) {
+        const territoryId = randomUUID();
+        const name = territoryName(keywords);
+        db.prepare(`INSERT INTO territories (id, map_id, name, category_id, keywords_count) VALUES (?, ?, ?, ?, ?)`)
+            .run(territoryId, mapId, name, categoryId, keywords.length);
+        for (const kw of keywords) {
+            db.prepare(`
+        INSERT INTO keywords (id, territory_id, map_id, keyword, volume, difficulty, domain, position, intent)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(randomUUID(), territoryId, mapId, kw.keyword, kw.volume, kw.difficulty, kw.domain, kw.position, kw.intent);
+        }
+    }
+    return {
+        map_id: mapId,
+        domain,
+        competitors,
+        territories_count: groups.size,
+        keywords_count: allKeywords.length,
+        created_at: new Date(now).toISOString(),
+    };
+}

package/dist/tools/get_gaps.js

@@ -0,0 +1,42 @@
+import { getDb } from '../db.js';
+export function getGaps(mapId, limit = 10) {
+    const db = getDb();
+    const map = db.prepare(`SELECT * FROM maps WHERE id = ?`).get(mapId);
+    if (!map)
+        throw new Error(`Map ${mapId} not found`);
+    const myDomain = map.domain;
+    const territories = db.prepare(`SELECT * FROM territories WHERE map_id = ?`).all(mapId);
+    const gaps = [];
+    for (const t of territories) {
+        const keywords = db.prepare(`
+      SELECT domain, COUNT(*) as count, SUM(volume) as total_volume
+      FROM keywords WHERE territory_id = ?
+      GROUP BY domain
+    `).all(t.id);
+        const totalCount = keywords.reduce((s, r) => s + r.count, 0);
+        const myRow = keywords.find((r) => r.domain === myDomain);
+        const myShare = myRow ? myRow.count / totalCount : 0;
+        // Best keyword in this territory (volume/difficulty ratio)
+        const bestKw = db.prepare(`
+      SELECT keyword, volume, difficulty
+      FROM keywords WHERE territory_id = ? AND volume > 0 AND difficulty > 0
+      ORDER BY (volume * 1.0 / difficulty) DESC LIMIT 1
+    `).get(t.id);
+        gaps.push({
+            territory_id: t.id,
+            name: t.name,
+            keywords_count: t.keywords_count,
+            my_share_pct: Math.round(myShare * 100),
+            gap_score: Math.round((1 - myShare) * 100),
+            best_keyword: bestKw ? {
+                keyword: bestKw.keyword,
+                volume: bestKw.volume,
+                difficulty: bestKw.difficulty,
+                opportunity_score: Math.round(bestKw.volume / (bestKw.difficulty || 1)),
+            } : null,
+        });
+    }
+    return gaps
+        .sort((a, b) => b.gap_score - a.gap_score)
+        .slice(0, limit);
+}

package/dist/tools/get_keywords.js

@@ -0,0 +1,30 @@
+import { getDb } from '../db.js';
+export function getKeywords(mapId, territoryId, limit = 20) {
+    const db = getDb();
+    const territory = db.prepare(`SELECT * FROM territories WHERE id = ? AND map_id = ?`).get(territoryId, mapId);
+    if (!territory)
+        throw new Error(`Territory ${territoryId} not found in map ${mapId}`);
+    const map = db.prepare(`SELECT domain FROM maps WHERE id = ?`).get(mapId);
+    const keywords = db.prepare(`
+    SELECT keyword, volume, difficulty, domain, position,
+           ROUND(volume * 1.0 / MAX(difficulty, 1)) as opportunity_score
+    FROM keywords
+    WHERE territory_id = ? AND volume > 0
+    ORDER BY opportunity_score DESC
+    LIMIT ?
+  `).all(territoryId, limit);
+    return {
+        territory_id: territoryId,
+        territory_name: territory.name,
+        my_domain: map.domain,
+        keywords: keywords.map(k => ({
+            keyword: k.keyword,
+            volume: k.volume,
+            difficulty: k.difficulty,
+            opportunity_score: k.opportunity_score,
+            current_owner: k.domain,
+            position: k.position,
+            owned_by_me: k.domain === map.domain,
+        })),
+    };
+}

package/dist/tools/get_territories.js

@@ -0,0 +1,33 @@
+import { getDb } from '../db.js';
+export function getTerritories(mapId) {
+    const db = getDb();
+    const map = db.prepare(`SELECT * FROM maps WHERE id = ?`).get(mapId);
+    if (!map)
+        throw new Error(`Map ${mapId} not found`);
+    const myDomain = map.domain;
+    const territories = db.prepare(`SELECT * FROM territories WHERE map_id = ?`).all(mapId);
+    return territories.map(t => {
+        const keywords = db.prepare(`
+      SELECT domain, COUNT(*) as count, SUM(volume) as total_volume
+      FROM keywords WHERE territory_id = ?
+      GROUP BY domain ORDER BY count DESC
+    `).all(t.id);
+        const totalCount = keywords.reduce((s, r) => s + r.count, 0);
+        const myRow = keywords.find((r) => r.domain === myDomain);
+        const myShare = myRow ? Math.round((myRow.count / totalCount) * 100) : 0;
+        const topOwner = keywords[0]?.domain ?? myDomain;
+        return {
+            territory_id: t.id,
+            name: t.name,
+            keywords_count: t.keywords_count,
+            my_share_pct: myShare,
+            top_owner: topOwner,
+            ownership: keywords.map((r) => ({
+                domain: r.domain,
+                keywords: r.count,
+                volume: r.total_volume,
+                share_pct: Math.round((r.count / totalCount) * 100),
+            })),
+        };
+    }).sort((a, b) => b.keywords_count - a.keywords_count);
+}

package/dist/tools/refresh.js

@@ -0,0 +1,54 @@
+import { getDb } from '../db.js';
+import { getRankedKeywords } from '../dataforseo.js';
+import { randomUUID } from 'node:crypto';
+function groupByCategory(keywords) {
+    const groups = new Map();
+    for (const kw of keywords) {
+        const cat = kw.categories[0] ?? 0;
+        if (!groups.has(cat))
+            groups.set(cat, []);
+        groups.get(cat).push(kw);
+    }
+    return groups;
+}
+function territoryName(keywords) {
+    return keywords.sort((a, b) => b.volume - a.volume)[0]?.keyword ?? 'uncategorized';
+}
+export async function refreshMap(mapId) {
+    const db = getDb();
+    const map = db.prepare(`SELECT * FROM maps WHERE id = ?`).get(mapId);
+    if (!map)
+        throw new Error(`Map ${mapId} not found`);
+    const domain = map.domain;
+    const competitors = JSON.parse(map.competitors);
+    const allDomains = [domain, ...competitors];
+    const results = await Promise.all(allDomains.map(d => getRankedKeywords(d)));
+    const allKeywords = results.flat();
+    if (allKeywords.length === 0)
+        throw new Error('No keywords found');
+    const prevCount = db.prepare(`SELECT COUNT(*) as c FROM territories WHERE map_id = ?`).get(mapId).c;
+    db.prepare(`DELETE FROM keywords WHERE map_id = ?`).run(mapId);
+    db.prepare(`DELETE FROM territories WHERE map_id = ?`).run(mapId);
+    const groups = groupByCategory(allKeywords);
+    const now = Date.now();
+    for (const [categoryId, keywords] of groups) {
+        const territoryId = randomUUID();
+        const name = territoryName(keywords);
+        db.prepare(`INSERT INTO territories (id, map_id, name, category_id, keywords_count) VALUES (?, ?, ?, ?, ?)`)
+            .run(territoryId, mapId, name, categoryId, keywords.length);
+        for (const kw of keywords) {
+            db.prepare(`
+        INSERT INTO keywords (id, territory_id, map_id, keyword, volume, difficulty, domain, position, intent)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(randomUUID(), territoryId, mapId, kw.keyword, kw.volume, kw.difficulty, kw.domain, kw.position, kw.intent);
+        }
+    }
+    db.prepare(`UPDATE maps SET refreshed_at = ? WHERE id = ?`).run(now, mapId);
+    return {
+        map_id: mapId,
+        territories_count: groups.size,
+        territories_drift: groups.size - prevCount,
+        keywords_count: allKeywords.length,
+        refreshed_at: new Date(now).toISOString(),
+    };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@silverbackbase/canopee",
+  "version": "0.1.0",
+  "description": "Semantic content territory mapping — MCP primitive for marketing agents",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/silverbackb/canopee.git"
+  },
+  "bin": {
+    "canopee":     "./dist/index.js",
+    "canopee-mcp": "./dist/mcp-stdio.js"
+  },
+  "keywords": ["seo", "content", "territory", "mcp", "dataforseo", "semantic"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "hono": "^4.3.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  }
+}