@amityco/foundry-mcp 0.1.0

package/dist/tools/resolve.js

@@ -0,0 +1,193 @@
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { harnessControlsFor } from "./harness.js";
+import { inspectProject } from "./project.js";
+export const resolveRequestTool = {
+    name: "resolve_request",
+    description: "Resolve a natural-language social.plus integration request into a support level and next tools.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            request: { type: "string" },
+            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");
+        const inspection = await inspectProject(repoPath, optionalStringField(args, "surfacePath"));
+        const outcome = classifyOutcome(request);
+        const supportLevel = supportFor(outcome, inspection.platforms);
+        return textResult({
+            outcome,
+            supportLevel,
+            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,
+            nextTools: nextToolsFor(outcome, supportLevel),
+            harness: harnessControlsFor(outcome, inspection.platforms),
+            notes: notesFor(outcome, supportLevel, inspection.platforms),
+        });
+    },
+};
+export const suggestPatchTool = {
+    name: "suggest_patch",
+    description: "Deprecated compatibility tool. Prefer plan_integration for grounded implementation planning. This tool does not write files.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            request: { type: "string" },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const request = stringField(args, "request");
+        const inspection = await inspectProject(repoPath);
+        const outcome = classifyOutcome(request);
+        return textResult({
+            deprecated: true,
+            replacement: "plan_integration",
+            writes: [],
+            outcome,
+            targetPlatforms: inspection.platforms,
+            plan: planFor(outcome, inspection.platforms),
+            harness: harnessControlsFor(outcome, inspection.platforms),
+            verification: verificationFor(outcome, inspection.platforms),
+            safety: "Read-only v1: no files were modified.",
+        });
+    },
+};
+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 supportFor(outcome, platforms) {
+    if (outcome === "unknown") {
+        return "unsupported";
+    }
+    if (platforms.length === 0) {
+        return "guided";
+    }
+    if (platforms.some((platform) => ["android", "flutter", "typescript", "react-native"].includes(platform))) {
+        return "supported";
+    }
+    if (platforms.includes("ios")) {
+        return "guided";
+    }
+    return "guided";
+}
+function nextToolsFor(outcome, supportLevel) {
+    if (supportLevel === "unsupported") {
+        return ["search_docs"];
+    }
+    if (outcome === "troubleshoot") {
+        return ["inspect_project", "search_docs", "get_doc_page", "validate_setup"];
+    }
+    return ["plan_harness", "plan_integration", "inspect_project", "search_docs", "get_doc_page", "validate_setup", "run_sensors"];
+}
+function notesFor(outcome, supportLevel, platforms) {
+    const notes = [];
+    if (platforms.length === 0) {
+        notes.push("No platform was detected. Ask for the app framework or point repoPath at the project root.");
+    }
+    if (platforms.includes("ios")) {
+        notes.push("iOS should be treated as guided until setup validation rules are expanded.");
+    }
+    if (supportLevel === "unsupported") {
+        notes.push("The request does not map to a known Foundry outcome.");
+    }
+    if (outcome === "setup-push") {
+        notes.push("Push setup usually needs customer-owned Firebase/APNS values; do not invent secrets or config IDs.");
+    }
+    if (outcome === "setup-live-data") {
+        notes.push("Live Object and Live Collection work needs an explicit lifecycle owner so observers can be cleaned up.");
+    }
+    return notes;
+}
+function planFor(outcome, platforms) {
+    const platform = platforms[0] ?? "unknown";
+    if (outcome === "setup-sdk" && platform === "android") {
+        return [
+            { file: "app/build.gradle or app/build.gradle.kts", intent: "Add the social.plus Android SDK dependency." },
+            { file: "Application class", intent: "Initialize the SDK once at app startup with API key and region." },
+            { file: "Login/auth flow", intent: "Call login after the app has a known user identity." },
+        ];
+    }
+    if (outcome === "setup-sdk" && platform === "flutter") {
+        return [
+            { file: "pubspec.yaml", intent: "Add the social.plus Flutter dependency." },
+            { file: "lib/main.dart", intent: "Ensure Flutter binding is initialized before SDK setup." },
+            { file: "Login/auth flow", intent: "Call login after the app has a known user identity." },
+        ];
+    }
+    if (outcome === "add-feed") {
+        return [
+            { file: "Target screen/component", intent: "Add a feed query and render loading, empty, error, and item states." },
+            { file: "Navigation route", intent: "Expose the feed surface from the existing app navigation." },
+        ];
+    }
+    if (outcome === "setup-push") {
+        return [
+            { file: "Platform notification config", intent: "Wire customer-owned Firebase/APNS configuration." },
+            { file: "Login/auth flow", intent: "Register the device after login and unregister on logout." },
+        ];
+    }
+    if (outcome === "setup-live-data") {
+        return [
+            { file: "Target screen/component/controller", intent: "Observe the Live Object or Live Collection and render loading, empty, error, and data states." },
+            { file: "Data source/repository module", intent: "Encapsulate get/query calls and clean up subscriptions when the lifecycle owner ends." },
+        ];
+    }
+    return [{ file: "customer app", intent: "Inspect the app and fetch relevant docs before proposing code changes." }];
+}
+function verificationFor(outcome, platforms) {
+    const checks = ["Run the app's normal build or typecheck command."];
+    if (outcome === "setup-sdk" || outcome === "validate-setup") {
+        checks.push("Confirm SDK setup runs before any social.plus API call.");
+        checks.push("Confirm API key and region match the customer's social.plus console project.");
+    }
+    if (outcome === "add-feed") {
+        checks.push("Confirm the feed screen handles loading, empty, error, and data states.");
+        checks.push("Confirm the feed query is scoped to the intended global, user, or community feed.");
+    }
+    if (outcome === "setup-push") {
+        checks.push("Confirm device registration happens after login.");
+        checks.push("Confirm unregister runs on logout or user switch.");
+    }
+    if (outcome === "setup-live-data") {
+        checks.push("Confirm Live Object/Collection observers clean up on unmount/dispose/disappear.");
+        checks.push("Confirm loading and error states are rendered before data is treated as ready.");
+    }
+    if (platforms.includes("android")) {
+        checks.push("For Android, confirm INTERNET permission exists in AndroidManifest.xml.");
+    }
+    return checks;
+}

package/dist/tools/sensors.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { objectInput, optionalNumberField, optionalStringField, stringField, textResult } from "../types.js";
+import { detectCommandSensors } from "./harness.js";
+import { inspectProject } from "./project.js";
+export const runSensorsTool = {
+    name: "run_sensors",
+    description: "Run detected project command sensors, such as build/typecheck/test, with a timeout and structured results.",
+    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. Used for traceability; command sensors are detected from the project.",
+            },
+            include: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional list of sensor names to run. If omitted, all detected command sensors run.",
+            },
+            timeoutMs: {
+                type: "number",
+                default: 120000,
+                description: "Per-command timeout in milliseconds.",
+            },
+            dryRun: {
+                type: "boolean",
+                default: false,
+                description: "If true, return detected sensors without executing commands.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const timeoutMs = Math.max(1000, Math.min(optionalNumberField(args, "timeoutMs", 120000), 600000));
+        const dryRun = args.dryRun === true;
+        const include = stringArrayField(args, "include");
+        const root = path.resolve(repoPath);
+        const inspection = await inspectProject(root, optionalStringField(args, "surfacePath"));
+        const detectedSensors = await detectCommandSensors(inspection.effectiveRoot, inspection.platforms);
+        const selectedSensors = include.length > 0 ? detectedSensors.filter((sensor) => include.includes(sensor.name)) : detectedSensors;
+        if (dryRun) {
+            return textResult({
+                status: "dry-run",
+                surfacePath: inspection.selectedSurface?.path,
+                targetPlatforms: inspection.platforms,
+                sensors: selectedSensors,
+            });
+        }
+        const results = [];
+        for (const sensor of selectedSensors) {
+            results.push(await runSensor(inspection.effectiveRoot, sensor, timeoutMs));
+        }
+        return textResult({
+            status: aggregateStatus(results),
+            surfacePath: inspection.selectedSurface?.path,
+            targetPlatforms: inspection.platforms,
+            results,
+            skipped: skippedSensors(detectedSensors, selectedSensors, include),
+        });
+    },
+};
+async function runSensor(cwd, sensor, timeoutMs) {
+    const startedAt = Date.now();
+    const [command, ...args] = sensor.command;
+    if (!command) {
+        return {
+            name: sensor.name,
+            command: sensor.command,
+            status: "skipped",
+            reason: "Sensor command is empty.",
+        };
+    }
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const child = spawn(command, args, {
+            cwd,
+            shell: false,
+            env: process.env,
+        });
+        const timeout = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            child.kill("SIGTERM");
+            resolve({
+                name: sensor.name,
+                command: sensor.command,
+                status: "timed-out",
+                durationMs: Date.now() - startedAt,
+                stdout: truncate(stdout),
+                stderr: truncate(stderr),
+                reason: `Timed out after ${timeoutMs}ms.`,
+            });
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({
+                name: sensor.name,
+                command: sensor.command,
+                status: "failed",
+                durationMs: Date.now() - startedAt,
+                stderr: truncate(error.message),
+                reason: "Failed to start sensor command.",
+            });
+        });
+        child.on("close", (exitCode) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({
+                name: sensor.name,
+                command: sensor.command,
+                status: exitCode === 0 ? "passed" : "failed",
+                exitCode,
+                durationMs: Date.now() - startedAt,
+                stdout: truncate(stdout),
+                stderr: truncate(stderr),
+            });
+        });
+    });
+}
+function aggregateStatus(results) {
+    if (results.length === 0) {
+        return "no-sensors";
+    }
+    if (results.some((result) => result.status === "timed-out")) {
+        return "timed-out";
+    }
+    if (results.some((result) => result.status === "failed")) {
+        return "failed";
+    }
+    return "passed";
+}
+function skippedSensors(detectedSensors, selectedSensors, include) {
+    const selectedNames = new Set(selectedSensors.map((sensor) => sensor.name));
+    const skipped = detectedSensors
+        .filter((sensor) => !selectedNames.has(sensor.name))
+        .map((sensor) => ({ name: sensor.name, reason: "Not selected by include filter." }));
+    for (const requestedName of include) {
+        if (!detectedSensors.some((sensor) => sensor.name === requestedName)) {
+            skipped.push({ name: requestedName, reason: "No detected sensor matched this include name." });
+        }
+    }
+    return skipped;
+}
+function stringArrayField(input, field) {
+    const value = input[field];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string" && item.trim() !== "");
+}
+function truncate(value, maxLength = 8000) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}\n[truncated ${value.length - maxLength} chars]`;
+}

package/dist/types.js

@@ -0,0 +1,31 @@
+export function textResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+export function objectInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        return {};
+    }
+    return input;
+}
+export function stringField(input, field) {
+    const value = input[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`Missing required string field: ${field}`);
+    }
+    return value;
+}
+export function optionalStringField(input, field) {
+    const value = input[field];
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+export function optionalNumberField(input, field, fallback) {
+    const value = input[field];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@amityco/foundry-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP server for social.plus SDK integration assistance.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmityCo/social-plus-foundry.git"
+  },
+  "homepage": "https://github.com/AmityCo/social-plus-foundry#readme",
+  "bugs": {
+    "url": "https://github.com/AmityCo/social-plus-foundry/issues"
+  },
+  "keywords": [
+    "social-plus",
+    "mcp",
+    "model-context-protocol",
+    "sdk",
+    "ai-coding"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "foundry-mcp": "dist/server.js",
+    "social-plus-foundry": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pack:check": "npm pack --dry-run --cache /private/tmp/social-plus-foundry-npm-cache",
+    "publish:check": "npm run validate && npm publish --dry-run --access public --cache /private/tmp/social-plus-foundry-npm-cache",
+    "start": "node dist/server.js",
+    "test": "npm run build && node test/run-fixtures.mjs",
+    "test:cli": "npm run build && node test/run-cli.mjs",
+    "test:improvements": "npm run build && node test/run-improvements.mjs",
+    "test:mcp": "npm run build && node test/run-mcp-smoke.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:improvements && npm run pack:check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.5"
+  }
+}