@amityco/foundry-mcp 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# Foundry MCP Server
+
+This is a small stdio MCP server for local social.plus integration assistance.
+
+The server can inspect repositories, detect design/theme signals, search hosted docs, plan harness guides/sensors, produce grounded integration plans with structured intake questions, validate setup patterns, and run detected project sensors.
+
+Frequent customer paths have dedicated guardrails:
+
+- notification setup: platform credentials, token source, registration after login, unregister on logout/user switch
+- Live Objects/Collections: object vs collection, observed domain, lifecycle owner, loading/error states, cleanup
+- monorepos: detected app surfaces can be selected with `surfacePath`
+
+`run_sensors` is constrained to detected project commands. It does not accept arbitrary shell input.
+
+## Commands
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+CLI checks:
+
+```sh
+node dist/server.js --version
+node dist/server.js doctor
+```
+
+Full local validation:
+
+```sh
+npm run validate
+```
+
+Product-oriented Foundry improvement discovery:
+
+```sh
+npm run test:improvements
+```
+
+## Docs Source
+
+By default, docs are read from:
+
+```text
+https://learn.social.plus/llms-full.txt
+```
+
+Maintainers can set `SOCIAL_PLUS_DOCS_ROOT` to test against a local `social-plus-docs` checkout.

package/dist/server.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
+import { planHarnessTool } from "./tools/harness.js";
+import { planIntegrationTool } from "./tools/integration.js";
+import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
+import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
+import { runSensorsTool } from "./tools/sensors.js";
+const tools = new Map([searchDocsTool, getDocPageTool, inspectProjectTool, planHarnessTool, planIntegrationTool, resolveRequestTool, runSensorsTool, validateSetupTool, suggestPatchTool].map((tool) => [
+    tool.name,
+    tool,
+]));
+const packageName = "@amityco/foundry-mcp";
+const packageVersion = "0.1.0";
+const cliResult = handleCli(process.argv.slice(2));
+if (cliResult === "exit") {
+    process.exit(0);
+}
+const server = new Server({
+    name: "social-plus-foundry",
+    version: packageVersion,
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: Array.from(tools.values()).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.get(request.params.name);
+    if (!tool) {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    return tool.call(request.params.arguments);
+});
+await server.connect(new StdioServerTransport());
+function handleCli(args) {
+    const command = args[0];
+    if (!command) {
+        return "serve";
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(`${packageName} ${packageVersion}`);
+        return "exit";
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        console.log(helpText());
+        return "exit";
+    }
+    if (command === "doctor" || command === "--doctor") {
+        console.log(JSON.stringify(doctorResult(), null, 2));
+        return "exit";
+    }
+    if (command.startsWith("-")) {
+        console.error(`Unknown option: ${command}`);
+        console.error("Run with --help for usage.");
+        return "exit";
+    }
+    return "serve";
+}
+function helpText() {
+    return `${packageName}
+
+Local MCP server for social.plus SDK integration assistance.
+
+Usage:
+  npx -y ${packageName}              Start the stdio MCP server
+  npx -y ${packageName} --help       Show this help
+  npx -y ${packageName} --version    Show package version
+  npx -y ${packageName} doctor       Print install diagnostics
+
+MCP config:
+  {
+    "mcpServers": {
+      "social-plus": {
+        "command": "npx",
+        "args": ["-y", "${packageName}"]
+      }
+    }
+  }
+
+Customers do not need environment variables. Maintainers may set
+SOCIAL_PLUS_DOCS_ROOT to test against a local social-plus-docs checkout.`;
+}
+function doctorResult() {
+    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    return {
+        package: packageName,
+        version: packageVersion,
+        status: nodeMajor >= 18 ? "ok" : "unsupported-node",
+        node: process.versions.node,
+        requiredNodeMajor: ">=18",
+        docsSource: process.env.SOCIAL_PLUS_DOCS_ROOT ? "local" : "hosted",
+        docsRoot: process.env.SOCIAL_PLUS_DOCS_ROOT,
+        docsBaseUrl: process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus",
+        transport: "stdio",
+        tools: Array.from(tools.keys()),
+    };
+}

package/dist/tools/docs.js

@@ -0,0 +1,255 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { objectInput, optionalNumberField, stringField, textResult } from "../types.js";
+let hostedPagesCache;
+function localDocsRoot() {
+    return process.env.SOCIAL_PLUS_DOCS_ROOT ? path.resolve(process.env.SOCIAL_PLUS_DOCS_ROOT) : undefined;
+}
+function docsBaseUrl() {
+    return (process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus").replace(/\/+$/, "");
+}
+export const searchDocsTool = {
+    name: "search_docs",
+    description: "Search social.plus documentation. Uses hosted docs by default and local docs only when SOCIAL_PLUS_DOCS_ROOT is set.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string" },
+            limit: { type: "number", default: 5 },
+        },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const query = stringField(args, "query");
+        const limit = optionalNumberField(args, "limit", 5);
+        return textResult({ results: await searchDocs(query, limit) });
+    },
+};
+export const getDocPageTool = {
+    name: "get_doc_page",
+    description: "Read a single social.plus docs page by docs path.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+        },
+        required: ["path"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const requestedPath = stringField(args, "path");
+        const page = await getDocPage(requestedPath);
+        return textResult(page);
+    },
+};
+async function searchDocs(query, limit) {
+    const pages = await loadDocPages();
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const results = [];
+    for (const page of pages) {
+        const lower = page.content.toLowerCase();
+        const pathAndTitle = `${page.path} ${page.title}`.toLowerCase();
+        let score = terms.reduce((sum, term) => {
+            const contentScore = countOccurrences(lower, term);
+            const metadataScore = countOccurrences(pathAndTitle, term) * 25;
+            return sum + contentScore + metadataScore;
+        }, 0);
+        if (terms.every((term) => pathAndTitle.includes(term))) {
+            score += 100;
+        }
+        if (score === 0) {
+            continue;
+        }
+        results.push({
+            path: page.path,
+            title: page.title,
+            snippet: snippetFor(page.content, terms),
+            score,
+        });
+    }
+    return results
+        .sort((a, b) => b.score - a.score)
+        .slice(0, Math.max(1, Math.min(limit, 20)))
+        .map(({ score: _score, ...result }) => result);
+}
+async function getDocPage(requestedPath) {
+    const normalized = normalizeDocsPath(requestedPath);
+    const pages = await loadDocPages();
+    const page = pages.find((candidate) => normalizeDocsPath(candidate.path) === normalized);
+    if (!page) {
+        throw new Error(`Docs page not found: ${requestedPath}. Use search_docs to find the canonical path.`);
+    }
+    return page;
+}
+async function loadDocPages() {
+    const root = localDocsRoot();
+    if (root) {
+        return loadLocalDocPages(root);
+    }
+    hostedPagesCache ??= loadHostedDocPages();
+    return hostedPagesCache;
+}
+async function loadHostedDocPages() {
+    const baseUrl = docsBaseUrl();
+    const fullUrl = `${baseUrl}/llms-full.txt`;
+    const indexUrl = `${baseUrl}/llms.txt`;
+    let content;
+    let pages;
+    try {
+        content = await fetchText(fullUrl);
+        pages = parseLlmsFull(content, baseUrl);
+    }
+    catch {
+        content = await fetchText(indexUrl);
+        pages = parseLlmsIndex(content, baseUrl);
+    }
+    if (pages.length === 0) {
+        throw new Error(`No docs pages found in ${fullUrl} or ${indexUrl}.`);
+    }
+    return pages;
+}
+async function loadLocalDocPages(root) {
+    const files = await findDocFiles(root);
+    return Promise.all(files.map(async (file) => {
+        const raw = await readFile(file, "utf8");
+        const content = cleanMdx(raw);
+        const relativePath = path.relative(root, file);
+        return {
+            path: relativePath,
+            title: titleFromContent(content, file),
+            content,
+        };
+    }));
+}
+async function fetchText(url) {
+    const response = await fetch(url, {
+        headers: {
+            accept: "text/plain, text/markdown, */*",
+            "user-agent": "social-plus-foundry-mcp/0.1.0",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch docs from ${url}: ${response.status} ${response.statusText}`);
+    }
+    return response.text();
+}
+function parseLlmsFull(content, baseUrl) {
+    const pageHeading = /^### \[([^\]]+)\]\(([^)]+)\)\s*$/gm;
+    const matches = Array.from(content.matchAll(pageHeading));
+    const pages = [];
+    for (let index = 0; index < matches.length; index += 1) {
+        const match = matches[index];
+        const nextMatch = matches[index + 1];
+        const title = match[1].trim();
+        const url = absolutizeUrl(match[2].trim(), baseUrl);
+        const start = (match.index ?? 0) + match[0].length;
+        const end = nextMatch?.index ?? content.length;
+        const pageContent = content.slice(start, end).trim();
+        pages.push({
+            path: pathFromDocsUrl(url),
+            title,
+            url,
+            content: cleanMdx(`# ${title}\n\n${pageContent}`),
+        });
+    }
+    return pages;
+}
+function parseLlmsIndex(content, baseUrl) {
+    const pageLine = /^- \[([^\]]+)\]\(([^)]+)\)(?::\s*(.*))?\s*$/gm;
+    const pages = [];
+    for (const match of content.matchAll(pageLine)) {
+        const title = match[1].trim();
+        const url = absolutizeUrl(match[2].trim(), baseUrl);
+        const summary = match[3]?.trim() || "No summary available.";
+        pages.push({
+            path: pathFromDocsUrl(url),
+            title,
+            url,
+            content: cleanMdx(`# ${title}\n\n${summary}`),
+        });
+    }
+    return pages;
+}
+function absolutizeUrl(url, baseUrl) {
+    return new URL(url, baseUrl).toString();
+}
+function pathFromDocsUrl(url) {
+    return normalizeDocsPath(new URL(url).pathname);
+}
+function normalizeDocsPath(docsPath) {
+    let normalized = docsPath.trim();
+    if (normalized.startsWith("http://") || normalized.startsWith("https://")) {
+        normalized = new URL(normalized).pathname;
+    }
+    normalized = normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+    normalized = normalized.replace(/\.(md|mdx)$/i, "");
+    return normalized;
+}
+function safeDocsPath(root, relativePath) {
+    const fullPath = path.resolve(root, relativePath);
+    if (!fullPath.startsWith(root + path.sep)) {
+        throw new Error("Docs path must stay inside social-plus-docs.");
+    }
+    return fullPath;
+}
+async function findDocFiles(root) {
+    const files = [];
+    async function walk(directory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".next") {
+                continue;
+            }
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+            }
+            else if (entry.name.endsWith(".md") || entry.name.endsWith(".mdx")) {
+                safeDocsPath(root, path.relative(root, entryPath));
+                files.push(entryPath);
+            }
+        }
+    }
+    await walk(root);
+    return files;
+}
+function cleanMdx(content) {
+    return content
+        .replace(/^---[\s\S]*?---\s*/m, "")
+        .replace(/^import .*$/gm, "")
+        .replace(/<[^>\n]+>/g, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function titleFromContent(content, file) {
+    const heading = content.match(/^#\s+(.+)$/m);
+    if (heading) {
+        return heading[1].trim();
+    }
+    return path.basename(file).replace(/\.(md|mdx)$/i, "");
+}
+function snippetFor(content, terms) {
+    const lower = content.toLowerCase();
+    const index = terms.map((term) => lower.indexOf(term)).filter((value) => value >= 0).sort((a, b) => a - b)[0] ?? 0;
+    const start = Math.max(0, index - 120);
+    const end = Math.min(content.length, index + 240);
+    return content.slice(start, end).replace(/\s+/g, " ").trim();
+}
+function countOccurrences(content, term) {
+    let count = 0;
+    let index = content.indexOf(term);
+    while (index >= 0) {
+        count += 1;
+        index = content.indexOf(term, index + term.length);
+    }
+    return count;
+}

package/dist/tools/harness.js

@@ -0,0 +1,246 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { inspectProject } from "./project.js";
+export function harnessControlsFor(outcome, platforms) {
+    const docsQuery = docsQueryFor(outcome, platforms);
+    return {
+        guides: [
+            {
+                name: "Resolve request",
+                kind: "guide",
+                execution: "computational",
+                timing: "before-change",
+                action: "resolve_request",
+                purpose: "Narrow the user's request into a known social.plus integration outcome.",
+            },
+            {
+                name: "Canonical docs",
+                kind: "guide",
+                execution: "computational",
+                timing: "before-change",
+                action: `search_docs query=\"${docsQuery}\"`,
+                purpose: "Load source-of-truth setup guidance before proposing code.",
+            },
+            {
+                name: "Integration plan",
+                kind: "guide",
+                execution: "inferential",
+                timing: "during-change",
+                action: "plan_integration",
+                purpose: "Give the coding agent an evidence-backed implementation packet before edits happen.",
+            },
+        ],
+        sensors: [
+            {
+                name: "Project inspection",
+                kind: "sensor",
+                execution: "computational",
+                timing: "before-change",
+                action: "inspect_project",
+                purpose: "Detect platform and framework signals from customer-owned files.",
+            },
+            {
+                name: "Setup validator",
+                kind: "sensor",
+                execution: "computational",
+                timing: "after-change",
+                action: "validate_setup",
+                purpose: "Catch common setup mistakes after the agent inspects or changes the app.",
+            },
+        ],
+        steeringLoop: [
+            "Resolve the request and inspect the project.",
+            "Fetch only the docs needed for the detected platform and outcome.",
+            "Generate a reviewable integration plan before edits.",
+            "Apply edits in the host coding agent, not inside Foundry v1.",
+            "Run deterministic sensors first: setup validation and detected project checks.",
+            "Use inferential review only after deterministic signals are available.",
+        ],
+    };
+}
+export const planHarnessTool = {
+    name: "plan_harness",
+    description: "Build the feedforward guides, feedback sensors, and steering loop for a social.plus SDK integration request.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: {
+                type: "string",
+                description: "Absolute or relative path to the customer repository root.",
+            },
+            request: {
+                type: "string",
+                description: "Natural-language integration request.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const request = stringField(args, "request");
+        return textResult(await buildHarnessPlan(repoPath, request, optionalStringField(args, "surfacePath")));
+    },
+};
+async function buildHarnessPlan(repoPath, request, surfacePath) {
+    const inspection = await inspectProject(repoPath, surfacePath);
+    const outcome = classifyOutcome(request);
+    const controls = harnessControlsFor(outcome, inspection.platforms);
+    const commandSensors = await detectCommandSensors(inspection.effectiveRoot, inspection.platforms);
+    const harnessability = assessHarnessability(inspection.platforms, commandSensors, inspection.designSignals.length);
+    return {
+        outcome,
+        surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+        availableSurfaces: inspection.surfaces.map((surface) => ({ path: surface.path, platforms: surface.platforms })),
+        targetPlatforms: inspection.platforms,
+        harnessability,
+        guides: controls.guides,
+        sensors: [...controls.sensors, ...commandSensors],
+        steeringLoop: controls.steeringLoop,
+    };
+}
+function classifyOutcome(request) {
+    const normalized = request.toLowerCase();
+    if (/\b(push|notification|firebase|fcm|apns)\b/.test(normalized)) {
+        return "setup-push";
+    }
+    if (/\b(live object|live objects|live collection|live collections|realtime collection|real-time collection|observe|observer|subscribe|subscription|unsubscribe|live update|live updates)\b/.test(normalized)) {
+        return "setup-live-data";
+    }
+    if (/\b(social feature|social features|feed|timeline|post list|news feed)\b/.test(normalized)) {
+        return "add-feed";
+    }
+    if (/\b(error|broken|crash|not working|fail|timeout|401|403)\b/.test(normalized)) {
+        return "troubleshoot";
+    }
+    if (/\b(validate|check|correct|setup right|initiali[sz])\b/.test(normalized)) {
+        return "validate-setup";
+    }
+    if (/\b(setup|set up|install|integrate|wire|configure)\b/.test(normalized)) {
+        return "setup-sdk";
+    }
+    return "unknown";
+}
+function docsQueryFor(outcome, platforms) {
+    const platform = platforms[0] ?? "sdk";
+    if (outcome === "setup-push") {
+        return `${platform} push notification setup`;
+    }
+    if (outcome === "add-feed") {
+        return `${platform} social feed posts`;
+    }
+    if (outcome === "setup-live-data") {
+        return `${platform} live objects live collections`;
+    }
+    if (outcome === "troubleshoot") {
+        return `${platform} troubleshooting authentication setup`;
+    }
+    return `${platform} quick start setup`;
+}
+export async function detectCommandSensors(repoPath, platforms) {
+    const root = path.resolve(repoPath);
+    const sensors = [];
+    if (platforms.includes("typescript") || platforms.includes("react-native")) {
+        sensors.push(...(await packageJsonSensors(root)));
+    }
+    if (platforms.includes("android") && (await exists(path.join(root, "gradlew")))) {
+        sensors.push({
+            name: "Android assemble",
+            command: ["./gradlew", "assembleDebug"],
+            timing: "after-change",
+            purpose: "Check Android project compilation after SDK setup changes.",
+            source: "gradlew",
+        }, {
+            name: "Android unit tests",
+            command: ["./gradlew", "test"],
+            timing: "after-change",
+            purpose: "Run available Android JVM tests after integration changes.",
+            source: "gradlew",
+        });
+    }
+    if (platforms.includes("flutter")) {
+        sensors.push({
+            name: "Flutter analyze",
+            command: ["flutter", "analyze"],
+            timing: "after-change",
+            purpose: "Check Dart static analysis after SDK setup changes.",
+            source: "pubspec.yaml",
+        }, {
+            name: "Flutter tests",
+            command: ["flutter", "test"],
+            timing: "after-change",
+            purpose: "Run available Flutter tests after integration changes.",
+            source: "pubspec.yaml",
+        });
+    }
+    return sensors;
+}
+async function packageJsonSensors(root) {
+    const packageJsonPath = path.join(root, "package.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const scripts = parsed.scripts ?? {};
+    const preferredScripts = ["typecheck", "build", "test", "lint"];
+    return preferredScripts
+        .filter((script) => scripts[script])
+        .map((script) => ({
+        name: `npm ${script}`,
+        command: ["npm", "run", script],
+        timing: "after-change",
+        purpose: `Run the project's ${script} script as a deterministic feedback sensor.`,
+        source: "package.json",
+    }));
+}
+function assessHarnessability(platforms, commandSensors, designSignalCount) {
+    const affordances = [];
+    const gaps = [];
+    if (platforms.length > 0) {
+        affordances.push(`Detected platform signals: ${platforms.join(", ")}.`);
+    }
+    else {
+        gaps.push("No platform signals detected; ask the user for the app framework or repository root.");
+    }
+    if (platforms.some((platform) => ["typescript", "react-native", "android", "flutter"].includes(platform))) {
+        affordances.push("Detected a platform with deterministic setup checks available in Foundry.");
+    }
+    if (commandSensors.length > 0) {
+        affordances.push(`Detected ${commandSensors.length} project command sensor(s).`);
+    }
+    else {
+        gaps.push("No project build/typecheck/test command sensors were detected yet.");
+    }
+    if (designSignalCount > 0) {
+        affordances.push(`Detected ${designSignalCount} design/theme signal(s) for UI integration grounding.`);
+    }
+    if (platforms.includes("ios")) {
+        gaps.push("iOS support is guided until deterministic validators are expanded.");
+    }
+    if (platforms.length === 0) {
+        return { level: "weak", affordances, gaps };
+    }
+    return {
+        level: commandSensors.length > 0 ? "strong" : "moderate",
+        affordances,
+        gaps,
+    };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}