@pixelsandclicks_/mcp-server 0.0.0-stage → 1.0.1

package/dist/data.d.ts

@@ -0,0 +1,5 @@
+import type { DeductionCode, Article } from "./types.js";
+export declare function loadDeductionCodes(): DeductionCode[];
+export declare function loadArticles(): Article[];
+export declare function deductionCodeUrl(slug: string): string;
+export declare function articleUrl(slug: string): string;

package/dist/data.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+const SITE_URL = "https://pixelsandclicks.net";
+function tryBundledJson(filename) {
+    const bundled = path.resolve(import.meta.dirname, "data", filename);
+    if (fs.existsSync(bundled)) {
+        return JSON.parse(fs.readFileSync(bundled, "utf-8"));
+    }
+    return null;
+}
+function findContentDir() {
+    let dir = path.resolve(import.meta.dirname, "..");
+    for (let i = 0; i < 5; i++) {
+        const candidate = path.join(dir, "src", "content");
+        if (fs.existsSync(candidate))
+            return candidate;
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+function slugFromFilename(filename) {
+    return path.basename(filename, path.extname(filename));
+}
+function loadCodesFromMarkdown(contentDir) {
+    const require = createRequire(import.meta.url);
+    const matter = require("gray-matter");
+    const codesDir = path.join(contentDir, "deductionCodes");
+    if (!fs.existsSync(codesDir))
+        return [];
+    return fs.readdirSync(codesDir)
+        .filter(f => f.endsWith(".md") || f.endsWith(".mdx"))
+        .map(filename => {
+        const raw = fs.readFileSync(path.join(codesDir, filename), "utf-8");
+        const { data } = matter(raw);
+        const slug = slugFromFilename(filename);
+        return {
+            slug,
+            retailer: data.retailer,
+            code: data.code,
+            codeName: data.codeName,
+            title: data.title,
+            description: data.description,
+            draft: data.draft ?? false,
+            family: data.family,
+            penalty: data.penalty,
+            disputableStatus: data.disputableStatus,
+            answer: data.answer,
+            answerQualifier: data.answerQualifier,
+            meaning: data.meaning,
+            meaningPoints: data.meaningPoints,
+            rootCauses: data.rootCauses ?? [],
+            rootCauseCategories: data.rootCauseCategories,
+            evidenceRequired: data.evidenceRequired ?? [],
+            disputable: data.disputable,
+            disputeWindow: data.disputeWindow,
+            prevention: data.prevention ?? [],
+            erpPrevention: data.erpPrevention,
+            faq: data.faq ?? [],
+        };
+    })
+        .filter(c => !c.draft);
+}
+function loadArticlesFromMarkdown(contentDir) {
+    const require = createRequire(import.meta.url);
+    const matter = require("gray-matter");
+    const articlesDir = path.join(contentDir, "articles");
+    if (!fs.existsSync(articlesDir))
+        return [];
+    return fs.readdirSync(articlesDir)
+        .filter(f => f.endsWith(".md") || f.endsWith(".mdx"))
+        .map(filename => {
+        const raw = fs.readFileSync(path.join(articlesDir, filename), "utf-8");
+        const { data } = matter(raw);
+        const slug = slugFromFilename(filename);
+        return {
+            slug,
+            title: data.title,
+            description: data.description,
+            author: data.author ?? "Pixels and Clicks",
+            tags: data.tags ?? [],
+            cluster: data.cluster,
+            draft: data.draft ?? false,
+            answer: data.answer,
+            answerQualifier: data.answerQualifier,
+            faq: data.faq ?? [],
+        };
+    })
+        .filter(a => !a.draft);
+}
+export function loadDeductionCodes() {
+    const bundled = tryBundledJson("codes.json");
+    if (bundled) {
+        return bundled
+            .filter(c => !c.draft)
+            .map(c => ({
+            ...c,
+            rootCauses: c.rootCauses ?? [],
+            evidenceRequired: c.evidenceRequired ?? [],
+            prevention: c.prevention ?? [],
+            faq: c.faq ?? [],
+        }));
+    }
+    const contentDir = findContentDir();
+    if (!contentDir)
+        return [];
+    return loadCodesFromMarkdown(contentDir);
+}
+export function loadArticles() {
+    const bundled = tryBundledJson("articles.json");
+    if (bundled) {
+        return bundled
+            .filter(a => !a.draft)
+            .map(a => ({
+            ...a,
+            author: a.author ?? "Pixels and Clicks",
+            tags: a.tags ?? [],
+            faq: a.faq ?? [],
+        }));
+    }
+    const contentDir = findContentDir();
+    if (!contentDir)
+        return [];
+    return loadArticlesFromMarkdown(contentDir);
+}
+export function deductionCodeUrl(slug) {
+    return `${SITE_URL}/deduction-codes/${slug}`;
+}
+export function articleUrl(slug) {
+    return `${SITE_URL}/articles/${slug}`;
+}

package/dist/search.d.ts

@@ -0,0 +1,8 @@
+import type { DeductionCode, Article, SearchResult } from "./types.js";
+export declare function searchDeductionCodes(codes: DeductionCode[], query: string, filters?: {
+    family?: string;
+    retailer?: string;
+}): SearchResult[];
+export declare function searchArticles(articles: Article[], query: string, filters?: {
+    cluster?: string;
+}): SearchResult[];

package/dist/search.js

@@ -0,0 +1,86 @@
+import { deductionCodeUrl, articleUrl } from "./data.js";
+function tokenize(text) {
+    return text.toLowerCase().split(/\s+/).filter(Boolean);
+}
+function scoreMatch(text, queryTokens) {
+    const lower = text.toLowerCase();
+    let score = 0;
+    for (const token of queryTokens) {
+        if (lower.includes(token)) {
+            score += 1;
+            // Bonus for exact word boundary match
+            if (new RegExp(`\\b${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(lower)) {
+                score += 0.5;
+            }
+        }
+    }
+    return score;
+}
+export function searchDeductionCodes(codes, query, filters) {
+    const queryTokens = tokenize(query);
+    let filtered = codes;
+    if (filters?.family) {
+        filtered = filtered.filter(c => c.family?.toLowerCase() === filters.family.toLowerCase());
+    }
+    if (filters?.retailer) {
+        filtered = filtered.filter(c => c.retailer.toLowerCase() === filters.retailer.toLowerCase());
+    }
+    return filtered
+        .map(code => {
+        const searchableText = [
+            code.title,
+            code.codeName,
+            code.code,
+            code.description,
+            code.meaning,
+            code.answer ?? "",
+            code.family ?? "",
+            ...(code.meaningPoints ?? []),
+            ...(code.prevention),
+        ].join(" ");
+        let relevance = scoreMatch(searchableText, queryTokens);
+        // Title and code-name matches are more likely what the user wants
+        relevance += scoreMatch(code.title, queryTokens) * 2;
+        relevance += scoreMatch(code.codeName, queryTokens) * 1.5;
+        return {
+            type: "deduction_code",
+            slug: code.slug,
+            title: code.title,
+            description: code.description,
+            relevance,
+            url: deductionCodeUrl(code.slug),
+        };
+    })
+        .filter(r => r.relevance > 0)
+        .sort((a, b) => b.relevance - a.relevance);
+}
+export function searchArticles(articles, query, filters) {
+    const queryTokens = tokenize(query);
+    let filtered = articles;
+    if (filters?.cluster) {
+        filtered = filtered.filter(a => a.cluster?.toLowerCase() === filters.cluster.toLowerCase());
+    }
+    return filtered
+        .map(article => {
+        const searchableText = [
+            article.title,
+            article.description,
+            article.answer ?? "",
+            article.tags.join(" "),
+            ...(article.faq.map(f => `${f.q} ${f.a}`)),
+        ].join(" ");
+        let relevance = scoreMatch(searchableText, queryTokens);
+        // Title matches are more likely what the user wants
+        relevance += scoreMatch(article.title, queryTokens) * 2;
+        return {
+            type: "article",
+            slug: article.slug,
+            title: article.title,
+            description: article.description,
+            relevance,
+            url: articleUrl(article.slug),
+        };
+    })
+        .filter(r => r.relevance > 0)
+        .sort((a, b) => b.relevance - a.relevance);
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,268 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { loadDeductionCodes, loadArticles, deductionCodeUrl, articleUrl, } from "./data.js";
+import { searchDeductionCodes, searchArticles } from "./search.js";
+const SITE_URL = "https://pixelsandclicks.net";
+export function createServer() {
+    const server = new McpServer({
+        name: "pixels-and-clicks",
+        version: "1.0.0",
+    });
+    const codes = loadDeductionCodes();
+    const articles = loadArticles();
+    // --- Tool 1: lookup_deduction_code ---
+    server.tool("lookup_deduction_code", "Look up a retail deduction code by retailer and code number. Returns meaning, root causes, evidence required, dispute path, prevention steps, and a link to the full reference on pixelsandclicks.net.", {
+        retailer: z.enum(["Walmart", "Target", "Amazon", "Kroger"]),
+        code: z.string().describe("Code number or identifier as it appears on the remittance, e.g. '22', 'ASN-ACC', 'SIFR'"),
+    }, async ({ retailer, code }) => {
+        const entry = codes.find((c) => c.retailer === retailer && c.code.toLowerCase() === code.toLowerCase());
+        if (!entry) {
+            const available = codes
+                .filter((c) => c.retailer === retailer)
+                .map((c) => `${c.code} (${c.codeName})`)
+                .join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `No entry found for ${retailer} code "${code}". Available ${retailer} codes: ${available || "none"}.\n\nBrowse all codes: ${SITE_URL}/deduction-codes`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        retailer: entry.retailer,
+                        code: entry.code,
+                        name: entry.codeName,
+                        family: entry.family,
+                        penalty: entry.penalty,
+                        disputableStatus: entry.disputableStatus,
+                        meaning: entry.meaning,
+                        meaningPoints: entry.meaningPoints,
+                        rootCauseCategories: entry.rootCauseCategories,
+                        rootCauses: entry.rootCauses.length > 0 ? entry.rootCauses : undefined,
+                        evidenceRequired: entry.evidenceRequired,
+                        disputable: entry.disputable,
+                        disputeWindow: entry.disputeWindow,
+                        prevention: entry.prevention,
+                        erpPrevention: entry.erpPrevention,
+                        answer: entry.answer,
+                        faq: entry.faq,
+                        url: deductionCodeUrl(entry.slug),
+                        source: "Pixels and Clicks — pixelsandclicks.net",
+                    }, null, 2),
+                }],
+        };
+    });
+    // --- Tool 2: search_deductions ---
+    server.tool("search_deductions", "Search across all retail deduction codes by keyword, symptom description, family (Shortage, Compliance, Pricing, Freight, ASN/EDI, Quality, Returns), or retailer. Returns matching codes ranked by relevance with links to pixelsandclicks.net.", {
+        query: z.string().describe("Search term: a keyword, symptom, or description like 'shortage', 'ASN mismatch', 'fill rate'"),
+        family: z.enum(["Shortage", "Compliance", "Pricing", "Freight", "ASN/EDI", "Quality", "Returns"]).optional(),
+        retailer: z.enum(["Walmart", "Target", "Amazon", "Kroger"]).optional(),
+    }, async ({ query, family, retailer }) => {
+        const results = searchDeductionCodes(codes, query, { family, retailer });
+        if (results.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No deduction codes matched "${query}". Browse all codes at ${SITE_URL}/deduction-codes`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        query,
+                        matches: results.slice(0, 10).map((r) => ({
+                            title: r.title,
+                            description: r.description,
+                            url: r.url,
+                        })),
+                        total: results.length,
+                        source: "Pixels and Clicks — pixelsandclicks.net",
+                    }, null, 2),
+                }],
+        };
+    });
+    // --- Tool 3: get_evidence_checklist ---
+    server.tool("get_evidence_checklist", "Get the dispute evidence checklist for a specific retail deduction code. Returns the documents and records a supplier needs before filing a dispute, with a link to the full reference on pixelsandclicks.net.", {
+        retailer: z.enum(["Walmart", "Target", "Amazon", "Kroger"]),
+        code: z.string().describe("Code number or identifier"),
+    }, async ({ retailer, code }) => {
+        const entry = codes.find((c) => c.retailer === retailer && c.code.toLowerCase() === code.toLowerCase());
+        if (!entry) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No entry found for ${retailer} code "${code}". Browse all codes: ${SITE_URL}/deduction-codes`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        retailer: entry.retailer,
+                        code: entry.code,
+                        name: entry.codeName,
+                        disputableStatus: entry.disputableStatus,
+                        disputeWindow: entry.disputeWindow,
+                        evidenceRequired: entry.evidenceRequired,
+                        disputable: entry.disputable,
+                        url: deductionCodeUrl(entry.slug),
+                        source: "Pixels and Clicks — pixelsandclicks.net",
+                    }, null, 2),
+                }],
+        };
+    });
+    // --- Tool 4: get_prevention_plan ---
+    server.tool("get_prevention_plan", "Get the prevention steps and ERP-specific blueprint for a retail deduction code. Includes concrete system configuration for NetSuite or Business Central where available. Links to pixelsandclicks.net.", {
+        retailer: z.enum(["Walmart", "Target", "Amazon", "Kroger"]),
+        code: z.string().describe("Code number or identifier"),
+        erp_system: z.string().optional().describe("ERP system name to filter for, e.g. 'NetSuite', 'Business Central'"),
+    }, async ({ retailer, code, erp_system }) => {
+        const entry = codes.find((c) => c.retailer === retailer && c.code.toLowerCase() === code.toLowerCase());
+        if (!entry) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No entry found for ${retailer} code "${code}". Browse all codes: ${SITE_URL}/deduction-codes`,
+                    }],
+            };
+        }
+        const result = {
+            retailer: entry.retailer,
+            code: entry.code,
+            name: entry.codeName,
+            prevention: entry.prevention,
+        };
+        if (entry.erpPrevention) {
+            if (!erp_system || entry.erpPrevention.system.toLowerCase().includes(erp_system.toLowerCase())) {
+                result.erpPrevention = entry.erpPrevention;
+            }
+            else {
+                result.erpNote = `ERP blueprint available for ${entry.erpPrevention.system}, but not specifically for "${erp_system}". The general prevention steps above still apply.`;
+            }
+        }
+        if (entry.rootCauseCategories) {
+            result.rootCauseCategories = entry.rootCauseCategories;
+        }
+        result.url = deductionCodeUrl(entry.slug);
+        result.source = "Pixels and Clicks — pixelsandclicks.net";
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // --- Tool 5: diagnose_remittance_line ---
+    server.tool("diagnose_remittance_line", "Given a remittance description, code, or symptom, identify which deduction codes match and return a triage summary: what each means, whether it's disputable, and what to do first. Links back to pixelsandclicks.net.", {
+        description: z.string().describe("The remittance line text, code number, or a description of the deduction, e.g. 'merchandise billed not shipped', 'shortage on PO 12345', 'ASN accuracy chargeback'"),
+        retailer: z.enum(["Walmart", "Target", "Amazon", "Kroger"]).optional(),
+    }, async ({ description, retailer }) => {
+        // First try exact code match
+        const codeMatch = description.match(/\b(?:code\s*)?(\d{1,3})\b/i);
+        if (codeMatch && retailer) {
+            const exact = codes.find((c) => c.retailer === retailer && c.code === codeMatch[1]);
+            if (exact) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                diagnosis: "exact_match",
+                                match: {
+                                    retailer: exact.retailer,
+                                    code: exact.code,
+                                    name: exact.codeName,
+                                    family: exact.family,
+                                    meaning: exact.meaning,
+                                    disputableStatus: exact.disputableStatus,
+                                    immediateAction: exact.evidenceRequired.length > 0
+                                        ? `Gather evidence first: ${exact.evidenceRequired[0]}`
+                                        : exact.disputable ?? "Review dispute options",
+                                    url: deductionCodeUrl(exact.slug),
+                                },
+                                source: "Pixels and Clicks — pixelsandclicks.net",
+                            }, null, 2),
+                        }],
+                };
+            }
+        }
+        // Fall back to search
+        const codeResults = searchDeductionCodes(codes, description, { retailer });
+        const articleResults = searchArticles(articles, description);
+        if (codeResults.length === 0 && articleResults.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No matching deduction codes or articles found for "${description}". Browse all codes at ${SITE_URL}/deduction-codes or all articles at ${SITE_URL}/articles`,
+                    }],
+            };
+        }
+        const topCodes = codeResults.slice(0, 5);
+        const topArticles = articleResults.slice(0, 3);
+        const matches = topCodes.map((r) => {
+            const code = codes.find((c) => c.slug === r.slug);
+            return {
+                code: `${code.retailer} ${code.code}`,
+                name: code.codeName,
+                family: code.family,
+                disputableStatus: code.disputableStatus,
+                summary: code.answer ?? code.meaning,
+                url: r.url,
+            };
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        diagnosis: "search_match",
+                        query: description,
+                        possibleCodes: matches,
+                        relatedArticles: topArticles.map((a) => ({
+                            title: a.title,
+                            url: a.url,
+                        })),
+                        source: "Pixels and Clicks — pixelsandclicks.net",
+                    }, null, 2),
+                }],
+        };
+    });
+    // --- Tool 6: get_article ---
+    server.tool("get_article", "Search for and retrieve a Pixels and Clicks article by topic keyword. Returns the answer field, FAQ, and a link to the full article on pixelsandclicks.net.", {
+        topic: z.string().describe("Topic to search for, e.g. 'OTIF fine', 'EDI 856', 'ASN rejections', 'NetSuite EDI'"),
+        cluster: z.enum(["prevention", "erp-technical", "forecasting", "recovery", "scoping"]).optional(),
+    }, async ({ topic, cluster }) => {
+        const results = searchArticles(articles, topic, { cluster });
+        if (results.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `No articles matched "${topic}". Browse all articles at ${SITE_URL}/articles`,
+                    }],
+            };
+        }
+        const topResult = articles.find((a) => a.slug === results[0].slug);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        title: topResult.title,
+                        description: topResult.description,
+                        answer: topResult.answer,
+                        answerQualifier: topResult.answerQualifier,
+                        tags: topResult.tags,
+                        cluster: topResult.cluster,
+                        faq: topResult.faq,
+                        url: articleUrl(topResult.slug),
+                        otherMatches: results.slice(1, 5).map((r) => ({
+                            title: r.title,
+                            url: r.url,
+                        })),
+                        source: "Pixels and Clicks — pixelsandclicks.net",
+                    }, null, 2),
+                }],
+        };
+    });
+    return server;
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+export interface DeductionCode {
+    slug: string;
+    retailer: "Walmart" | "Target" | "Kroger" | "Amazon";
+    code: string;
+    codeName: string;
+    title: string;
+    description: string;
+    draft: boolean;
+    family?: string;
+    penalty?: string;
+    disputableStatus?: string;
+    answer?: string;
+    answerQualifier?: string;
+    meaning: string;
+    meaningPoints?: string[];
+    rootCauses: string[];
+    rootCauseCategories?: {
+        physical?: string;
+        carrier?: string;
+        erp?: string;
+    };
+    evidenceRequired: string[];
+    disputable?: string;
+    disputeWindow?: string;
+    prevention: string[];
+    erpPrevention?: {
+        system: string;
+        blueprint: string;
+    };
+    faq: Array<{
+        q: string;
+        a: string;
+    }>;
+}
+export interface Article {
+    slug: string;
+    title: string;
+    description: string;
+    author: string;
+    tags: string[];
+    cluster?: string;
+    draft: boolean;
+    answer?: string;
+    answerQualifier?: string;
+    faq: Array<{
+        q: string;
+        a: string;
+    }>;
+}
+export interface SearchResult {
+    type: "deduction_code" | "article";
+    slug: string;
+    title: string;
+    description: string;
+    relevance: number;
+    url: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@pixelsandclicks_/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "type": "module",
+  "description": "MCP server for retail deduction codes, dispute evidence, and supplier-ops knowledge from Pixels and Clicks",
+  "bin": {
+    "mcp-server": "dist/cli.js",
+    "pixelsandclicks-mcp": "dist/cli.js"
+  },
+  "main": "./dist/server.js",
+  "scripts": {
+    "build": "tsc && node scripts/bundle-content.js",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.8"
+  },
+  "optionalDependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.14.0"
+  },
+  "keywords": [
+    "mcp",
+    "retail",
+    "deductions",
+    "walmart",
+    "amazon",
+    "target",
+    "supplier",
+    "supply-chain"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pixelsandclicks/pixels-and-clicks",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://pixelsandclicks.net"
+}