@askthew/mcp-plugin 0.2.0

package/README.md

@@ -0,0 +1,122 @@
+# Ask The W MCP Plugin
+
+Connect a local coding agent to Ask The W.
+
+This package runs a small MCP server that lets Codex, Claude Code, Cursor, and other MCP-capable tools send compact work-session signals to an Ask The W workspace.
+
+## What It Does
+
+- Installs an Ask The W MCP server entry into a supported local client.
+- Preserves existing MCP servers and settings.
+- Sends a startup heartbeat so Ask The W can show that the plugin was seen.
+- Exposes one primary MCP tool: `capture_session_signal`.
+- Redacts obvious secrets from summaries, evidence excerpts, commands, and metadata before sending.
+- Adds lightweight workspace metadata such as host type, repo name, app path, and server name.
+
+## What It Does Not Do
+
+- It does not send full transcripts by default.
+- It does not infer decisions locally.
+- It does not link outcomes, score confidence, dedupe signals, or update the graph locally.
+- It does not include the Ask The W app, private server code, Supabase code, or internal analytics code.
+
+Ask The W performs inference, linking, approval state, dedupe, and outcome updates in the app.
+
+## Install
+
+Create a workspace token in Ask The W, then run the installer from your coding agent or terminal.
+
+Codex:
+
+```bash
+npx -y @askthew/mcp-plugin@latest install \
+  --host codex \
+  --token "<ASKTHEW_INSTALL_TOKEN>" \
+  --api-url "https://app.askthew.com/" \
+  --server-name "askthew"
+```
+
+Claude Code:
+
+```bash
+npx -y @askthew/mcp-plugin@latest install \
+  --host claude_code \
+  --token "<ASKTHEW_INSTALL_TOKEN>" \
+  --api-url "https://app.askthew.com/" \
+  --server-name "askthew"
+```
+
+Cursor:
+
+```bash
+npx -y @askthew/mcp-plugin@latest install \
+  --host cursor \
+  --token "<ASKTHEW_INSTALL_TOKEN>" \
+  --api-url "https://app.askthew.com/" \
+  --server-name "askthew"
+```
+
+After install, restart or reload your coding agent if needed.
+
+## Configuration
+
+The installer writes an MCP server entry like this:
+
+```json
+{
+  "mcpServers": {
+    "askthew": {
+      "command": "npx",
+      "args": ["-y", "@askthew/mcp-plugin@latest"],
+      "env": {
+        "ASKTHEW_INSTALL_TOKEN": "<ASKTHEW_INSTALL_TOKEN>",
+        "ASKTHEW_HOST_TYPE": "codex",
+        "ASKTHEW_API_URL": "https://app.askthew.com/",
+        "ASKTHEW_SERVER_NAME": "askthew"
+      }
+    }
+  }
+}
+```
+
+Optional environment variables:
+
+- `ASKTHEW_CLIENT_ID`
+- `ASKTHEW_CLIENT_LABEL`
+
+## Tool Contract
+
+The public tool surface is intentionally small.
+
+```json
+{
+  "name": "capture_session_signal",
+  "input": {
+    "sessionId": "string",
+    "sequence": "number",
+    "kind": "setup_complete | session_checkpoint | direction_change | implementation_update | verification_result | final_summary",
+    "summary": "string",
+    "evidence": [{ "role": "user | assistant | system", "excerpt": "string" }],
+    "filesTouched": ["string"],
+    "commandsRun": ["string"],
+    "metadata": {}
+  }
+}
+```
+
+Use compact summaries and short evidence excerpts. Do not send full transcripts.
+
+## Troubleshooting
+
+- Empty `list_mcp_resources` or `list_mcp_resource_templates` results are normal. This connector is tool-driven.
+- If Ask The W shows "Waiting for install", restart or reload your coding agent.
+- If Ask The W shows "Installed", ask your coding agent to send the first setup check.
+- If a token fails, rotate it in Ask The W and rerun the installer.
+
+## Development
+
+```bash
+npm run build --workspace @askthew/mcp-plugin
+npm test --workspace @askthew/mcp-plugin
+npm pack --workspace @askthew/mcp-plugin --dry-run
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createAskTheWMcpServer } from "./index.js";
+import { createHostConfigSnippet, formatInstallCommand, installHostConfig, } from "./install.js";
+function usage() {
+    return [
+        "AskTheW Coding Agent Connector",
+        "",
+        "Usage:",
+        "  askthew-mcp",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>] [--dry-run]",
+        "  askthew-mcp print-config --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>]",
+    ].join("\n");
+}
+function parseInstallArgs(argv) {
+    let hostType;
+    let clientId = process.env.ASKTHEW_CLIENT_ID?.trim() || "";
+    let clientLabel = process.env.ASKTHEW_CLIENT_LABEL?.trim() || "";
+    let token = normalizeInstallToken(process.env.ASKTHEW_INSTALL_TOKEN) || "";
+    let apiUrl = process.env.ASKTHEW_API_URL?.trim() || "";
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "";
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next) {
+            throw new Error(`Missing value for ${argument}.`);
+        }
+        if (argument === "--host") {
+            if (next !== "claude_code" && next !== "codex" && next !== "cursor") {
+                throw new Error(`Unsupported host "${next}". Expected claude_code, codex, or cursor.`);
+            }
+            hostType = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--client-id") {
+            clientId = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--client-label") {
+            clientLabel = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--token") {
+            token = normalizeInstallToken(next);
+            index += 1;
+            continue;
+        }
+        if (argument === "--api-url") {
+            apiUrl = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--server-name") {
+            serverName = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (!hostType) {
+        throw new Error("Missing required --host argument.");
+    }
+    if (!token) {
+        throw new Error("Missing required --token argument.");
+    }
+    if (!apiUrl) {
+        throw new Error("Missing required --api-url argument.");
+    }
+    if (!serverName) {
+        throw new Error("Missing required --server-name argument.");
+    }
+    return {
+        hostType,
+        clientId: clientId || undefined,
+        clientLabel: clientLabel || undefined,
+        token,
+        apiUrl,
+        serverName,
+        dryRun,
+    };
+}
+function normalizeInstallToken(token) {
+    return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
+}
+async function main() {
+    const [command, ...argv] = process.argv.slice(2);
+    if (command === "--help" || command === "-h" || command === "help") {
+        console.log(usage());
+        return;
+    }
+    if (command === "print-config") {
+        const options = parseInstallArgs(argv);
+        const snippet = createHostConfigSnippet(options);
+        console.log(snippet.json);
+        return;
+    }
+    if (command === "install") {
+        const options = parseInstallArgs(argv);
+        const result = installHostConfig(options);
+        console.log(result.wroteFile ? "AskTheW plugin install complete." : "AskTheW plugin dry run complete.");
+        console.log(`Settings path: ${result.settingsPath}`);
+        console.log(`Install command: ${formatInstallCommand(options)}`);
+        console.log(`Next step: ${result.nextStep}`);
+        if (!result.wroteFile) {
+            console.log("");
+            console.log(result.json);
+        }
+        return;
+    }
+    if (command) {
+        throw new Error(`Unknown command "${command}".\n\n${usage()}`);
+    }
+    const server = createAskTheWMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    if (error instanceof Error) {
+        console.error(error.message);
+    }
+    else {
+        console.error("AskTheW plugin failed to start.", error);
+    }
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare const codingSessionSignalSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    sequence: z.ZodNumber;
+    kind: z.ZodEnum<["setup_complete", "session_checkpoint", "direction_change", "implementation_update", "verification_result", "final_summary"]>;
+    summary: z.ZodString;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant", "system"]>;
+        excerpt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        role: "user" | "assistant" | "system";
+        excerpt: string;
+    }, {
+        role: "user" | "assistant" | "system";
+        excerpt: string;
+    }>, "many">>;
+    filesTouched: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    commandsRun: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    sequence: number;
+    kind: "setup_complete" | "session_checkpoint" | "direction_change" | "implementation_update" | "verification_result" | "final_summary";
+    summary: string;
+    evidence: {
+        role: "user" | "assistant" | "system";
+        excerpt: string;
+    }[];
+    filesTouched: string[];
+    commandsRun: string[];
+    metadata: Record<string, unknown>;
+}, {
+    sessionId: string;
+    sequence: number;
+    kind: "setup_complete" | "session_checkpoint" | "direction_change" | "implementation_update" | "verification_result" | "final_summary";
+    summary: string;
+    evidence?: {
+        role: "user" | "assistant" | "system";
+        excerpt: string;
+    }[] | undefined;
+    filesTouched?: string[] | undefined;
+    commandsRun?: string[] | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type CodingSessionSignal = z.infer<typeof codingSessionSignalSchema>;
+export declare const provenanceSignalSchema: z.ZodObject<{
+    source: z.ZodString;
+    decision: z.ZodString;
+    rationale: z.ZodString;
+    confidence: z.ZodNumber;
+    framework: z.ZodOptional<z.ZodString>;
+    filesAffected: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    sessionId: z.ZodString;
+    pendingApproval: z.ZodOptional<z.ZodBoolean>;
+    originatingPrompt: z.ZodOptional<z.ZodString>;
+    installToken: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    metadata: Record<string, unknown>;
+    source: string;
+    decision: string;
+    rationale: string;
+    confidence: number;
+    filesAffected: string[];
+    framework?: string | undefined;
+    pendingApproval?: boolean | undefined;
+    originatingPrompt?: string | undefined;
+    installToken?: string | undefined;
+}, {
+    sessionId: string;
+    source: string;
+    decision: string;
+    rationale: string;
+    confidence: number;
+    metadata?: Record<string, unknown> | undefined;
+    framework?: string | undefined;
+    filesAffected?: string[] | undefined;
+    pendingApproval?: boolean | undefined;
+    originatingPrompt?: string | undefined;
+    installToken?: string | undefined;
+}>;
+export type ProvenanceSignal = z.infer<typeof provenanceSignalSchema>;
+export declare function inferFunctionalArea(signal: Pick<ProvenanceSignal, "filesAffected">): string;
+export declare function redactProvenanceSignal(input: ProvenanceSignal): {
+    originatingPrompt: string | undefined;
+    metadata: {
+        functional_area: string;
+    };
+    sessionId: string;
+    source: string;
+    decision: string;
+    rationale: string;
+    confidence: number;
+    filesAffected: string[];
+    framework?: string | undefined;
+    pendingApproval?: boolean | undefined;
+    installToken?: string | undefined;
+};
+export declare function redactCodingSessionSignal(input: CodingSessionSignal): {
+    summary: string;
+    evidence: {
+        excerpt: string;
+        role: "user" | "assistant" | "system";
+    }[];
+    commandsRun: string[];
+    metadata: Record<string, unknown>;
+    sessionId: string;
+    sequence: number;
+    kind: "setup_complete" | "session_checkpoint" | "direction_change" | "implementation_update" | "verification_result" | "final_summary";
+    filesTouched: string[];
+};
+export declare function normalizeInstallTokenInput(token: string | undefined): string;
+export declare function createAskTheWMcpServer(): McpServer;

package/dist/index.js

@@ -0,0 +1,268 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveFunctionalAreaFromToml, resolvePluginScope } from "./scope.js";
+const evidenceRoleSchema = z.enum(["user", "assistant", "system"]);
+const sessionSignalKindSchema = z.enum([
+    "setup_complete",
+    "session_checkpoint",
+    "direction_change",
+    "implementation_update",
+    "verification_result",
+    "final_summary",
+]);
+export const codingSessionSignalSchema = z.object({
+    sessionId: z.string().min(1),
+    sequence: z.number().int().nonnegative(),
+    kind: sessionSignalKindSchema,
+    summary: z.string().min(1).max(2000),
+    evidence: z
+        .array(z.object({
+        role: evidenceRoleSchema,
+        excerpt: z.string().min(1).max(500),
+    }))
+        .default([]),
+    filesTouched: z.array(z.string().min(1).max(500)).default([]),
+    commandsRun: z.array(z.string().min(1).max(500)).default([]),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export const provenanceSignalSchema = z.object({
+    source: z.string().min(1),
+    decision: z.string().min(1),
+    rationale: z.string().min(1),
+    confidence: z.number().min(0).max(1),
+    framework: z.string().optional(),
+    filesAffected: z.array(z.string()).default([]),
+    sessionId: z.string().min(1),
+    pendingApproval: z.boolean().optional(),
+    originatingPrompt: z.string().optional(),
+    installToken: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+});
+const REDACTION_PATTERNS = [
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+    /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\b/g,
+    /\b[A-Za-z0-9_-]{32,}\b/g,
+];
+function redactSecrets(text) {
+    return REDACTION_PATTERNS.reduce((accumulator, pattern) => accumulator.replace(pattern, "[REDACTED]"), text);
+}
+function redactMetadata(value) {
+    if (typeof value === "string") {
+        return redactSecrets(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => redactMetadata(entry));
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactMetadata(entry)]));
+    }
+    return value;
+}
+export function inferFunctionalArea(signal) {
+    const explicit = process.env.ASKTHEW_FUNCTIONAL_AREA?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    const configuredArea = resolveFunctionalAreaFromToml(process.cwd());
+    if (configuredArea) {
+        return configuredArea;
+    }
+    const files = (signal.filesAffected ?? []).map((file) => file.toLowerCase());
+    if (files.length > 0 && files.every((file) => file.includes("test"))) {
+        return "QA";
+    }
+    if (files.length > 0 && files.every((file) => file.includes("marketing") || file.includes("content"))) {
+        return "Marketing";
+    }
+    if (files.length > 0 && files.every((file) => file.includes("design"))) {
+        return "Design";
+    }
+    if (fs.existsSync(path.resolve(process.cwd(), "figma.config")) || fs.existsSync(path.resolve(process.cwd(), ".sketch"))) {
+        return "Design";
+    }
+    if (fs.existsSync(path.resolve(process.cwd(), "campaign.yml"))) {
+        return "Marketing";
+    }
+    const repoMarkers = ["package.json", "pyproject.toml", "go.mod", "Cargo.toml"];
+    if (repoMarkers.some((marker) => fs.existsSync(path.resolve(process.cwd(), marker)))) {
+        return "Engineering";
+    }
+    return "Engineering";
+}
+export function redactProvenanceSignal(input) {
+    const parsed = provenanceSignalSchema.parse(input);
+    return {
+        ...parsed,
+        originatingPrompt: typeof parsed.originatingPrompt === "string"
+            ? redactSecrets(parsed.originatingPrompt)
+            : undefined,
+        metadata: {
+            ...parsed.metadata,
+            functional_area: inferFunctionalArea(parsed),
+        },
+    };
+}
+export function redactCodingSessionSignal(input) {
+    const parsed = codingSessionSignalSchema.parse(input);
+    return {
+        ...parsed,
+        summary: redactSecrets(parsed.summary),
+        evidence: parsed.evidence.map((entry) => ({
+            ...entry,
+            excerpt: redactSecrets(entry.excerpt),
+        })),
+        commandsRun: parsed.commandsRun.map((command) => redactSecrets(command)),
+        metadata: redactMetadata(parsed.metadata),
+    };
+}
+function apiBaseUrl() {
+    return process.env.ASKTHEW_API_URL?.trim() || "https://app.askthew.com";
+}
+function normalizeClientId(value) {
+    return String(value ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 64);
+}
+export function normalizeInstallTokenInput(token) {
+    return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
+}
+function credentials() {
+    const legacyHostType = process.env.ASKTHEW_HOST_TYPE?.trim();
+    const hostType = legacyHostType === "claude_code" || legacyHostType === "codex" || legacyHostType === "cursor"
+        ? legacyHostType
+        : undefined;
+    const clientId = normalizeClientId(process.env.ASKTHEW_CLIENT_ID?.trim()) || hostType || "mcp_client";
+    return {
+        installToken: normalizeInstallTokenInput(process.env.ASKTHEW_INSTALL_TOKEN),
+        userId: process.env.ASKTHEW_USER_ID?.trim(),
+        apiKey: process.env.ASKTHEW_API_KEY?.trim(),
+        serverName: process.env.ASKTHEW_SERVER_NAME?.trim(),
+        clientId,
+        clientLabel: process.env.ASKTHEW_CLIENT_LABEL?.trim(),
+        hostType,
+    };
+}
+function hasServerIdentity() {
+    const { installToken, userId } = credentials();
+    return Boolean(installToken || userId);
+}
+async function postToServer(route, payload) {
+    if (!hasServerIdentity()) {
+        return null;
+    }
+    const { installToken, userId, apiKey, clientId, clientLabel, hostType } = credentials();
+    const response = await fetch(`${apiBaseUrl()}${route}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+            ...payload,
+            installToken: installToken || undefined,
+            userId: userId || undefined,
+            clientId,
+            clientLabel: clientLabel || undefined,
+            hostType: hostType || undefined,
+        }),
+    }).catch(() => null);
+    if (!response || !response.ok) {
+        return null;
+    }
+    return response.json().catch(() => null);
+}
+function runtimeMetadata() {
+    const scope = resolvePluginScope(process.cwd());
+    const { serverName, clientId, clientLabel } = credentials();
+    return {
+        repository: scope.repoName,
+        repo_name: scope.repoName,
+        ...(scope.repoRoot ? { repo_root: scope.repoRoot } : {}),
+        ...(scope.appPath ? { app_path: scope.appPath } : {}),
+        ...(scope.serviceName ? { service_name: scope.serviceName } : {}),
+        ...(serverName ? { server_name: serverName } : {}),
+        ...(clientId ? { client_id: clientId } : {}),
+        ...(clientLabel ? { client_label: clientLabel } : {}),
+    };
+}
+async function sendStartupHeartbeat() {
+    if (!hasServerIdentity()) {
+        return;
+    }
+    const { installToken, apiKey, clientId, clientLabel, hostType, serverName } = credentials();
+    if (!installToken) {
+        return;
+    }
+    const scope = resolvePluginScope(process.cwd());
+    await fetch(`${apiBaseUrl()}/api/connectors/mcp/heartbeat`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+            installToken,
+            clientId,
+            ...(clientLabel ? { clientLabel } : {}),
+            hostType,
+            ...(serverName ? { serverName } : {}),
+            repoName: scope.repoName,
+            ...(scope.repoRoot ? { repoRoot: scope.repoRoot } : {}),
+            ...(scope.appPath ? { appPath: scope.appPath } : {}),
+            ...(scope.serviceName ? { serviceName: scope.serviceName } : {}),
+        }),
+    }).catch(() => null);
+}
+export function createAskTheWMcpServer() {
+    const server = new McpServer({
+        name: "AskTheW Coding Agent Connector",
+        version: "1.0.0",
+    });
+    void sendStartupHeartbeat();
+    server.tool("capture_session_signal", {
+        sessionId: z.string().min(1),
+        sequence: z.number().int().nonnegative(),
+        kind: sessionSignalKindSchema,
+        summary: z.string().min(1).max(2000),
+        evidence: z
+            .array(z.object({
+            role: evidenceRoleSchema,
+            excerpt: z.string().min(1).max(500),
+        }))
+            .default([]),
+        filesTouched: z.array(z.string().min(1).max(500)).default([]),
+        commandsRun: z.array(z.string().min(1).max(500)).default([]),
+        metadata: z.record(z.string(), z.unknown()).default({}),
+    }, async (payload) => {
+        const sessionSignal = redactCodingSessionSignal({
+            ...payload,
+            metadata: {
+                ...runtimeMetadata(),
+                ...(payload.metadata ?? {}),
+            },
+        });
+        const upstream = await postToServer("/api/ingest/mcp", {
+            sessionSignal,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: true,
+                        signal: sessionSignal,
+                        upstream,
+                        note: "Ask The W stores this as source material and performs inference in the app.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    return server;
+}

package/dist/install.d.ts

@@ -0,0 +1,65 @@
+export type SupportedHostType = "claude_code" | "codex" | "cursor";
+interface HostConfigInput {
+    hostType: SupportedHostType;
+    token: string;
+    apiUrl: string;
+    serverName: string;
+    clientId?: string;
+    clientLabel?: string;
+}
+interface InstallHostConfigInput extends HostConfigInput {
+    dryRun?: boolean;
+    homeDirectory?: string;
+}
+export declare function resolveSettingsPath(input: {
+    hostType: SupportedHostType;
+    homeDirectory?: string;
+}): string;
+export declare function createServerEntry(input: HostConfigInput): {
+    command: string;
+    args: string[];
+    env: {
+        ASKTHEW_HOST_TYPE: SupportedHostType;
+        ASKTHEW_SERVER_NAME: string;
+        ASKTHEW_CLIENT_LABEL?: string | undefined;
+        ASKTHEW_CLIENT_ID?: string | undefined;
+        ASKTHEW_INSTALL_TOKEN: string;
+        ASKTHEW_API_URL: string;
+    };
+};
+export declare function createHostConfigSnippet(input: HostConfigInput): {
+    settingsPath: string;
+    snippet: {
+        mcpServers: {
+            [input.serverName]: {
+                command: string;
+                args: string[];
+                env: {
+                    ASKTHEW_HOST_TYPE: SupportedHostType;
+                    ASKTHEW_SERVER_NAME: string;
+                    ASKTHEW_CLIENT_LABEL?: string | undefined;
+                    ASKTHEW_CLIENT_ID?: string | undefined;
+                    ASKTHEW_INSTALL_TOKEN: string;
+                    ASKTHEW_API_URL: string;
+                };
+            };
+        };
+    };
+    json: string;
+};
+export declare function mergeHostSettings(input: HostConfigInput & {
+    existingSettings: unknown;
+}): {
+    mcpServers: {
+        [x: string]: unknown;
+    };
+};
+export declare function formatInstallCommand(input: HostConfigInput): string;
+export declare function verificationNextStep(hostType: SupportedHostType): string;
+export declare function installHostConfig(input: InstallHostConfigInput): {
+    settingsPath: string;
+    json: string;
+    wroteFile: boolean;
+    nextStep: string;
+};
+export {};

package/dist/install.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function resolveSettingsPath(input) {
+    const homeDirectory = input.homeDirectory ?? os.homedir();
+    const configDirectory = input.hostType === "claude_code" ? ".claude" : ".codex";
+    return path.join(homeDirectory, configDirectory, "settings.json");
+}
+export function createServerEntry(input) {
+    return {
+        command: "npx",
+        args: ["-y", "@askthew/mcp-plugin@latest"],
+        env: {
+            ASKTHEW_INSTALL_TOKEN: input.token,
+            ASKTHEW_API_URL: input.apiUrl,
+            ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
+            ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
+            ASKTHEW_HOST_TYPE: input.hostType,
+            ASKTHEW_SERVER_NAME: input.serverName,
+        },
+    };
+}
+export function createHostConfigSnippet(input) {
+    const snippet = {
+        mcpServers: {
+            [input.serverName]: createServerEntry(input),
+        },
+    };
+    return {
+        settingsPath: resolveSettingsPath({ hostType: input.hostType }),
+        snippet,
+        json: JSON.stringify(snippet, null, 2),
+    };
+}
+export function mergeHostSettings(input) {
+    const existingSettings = isRecord(input.existingSettings) ? input.existingSettings : {};
+    const existingMcpServers = isRecord(existingSettings.mcpServers) ? existingSettings.mcpServers : {};
+    const nextMcpServers = { ...existingMcpServers };
+    if (input.serverName !== "askthew" && "askthew" in nextMcpServers) {
+        delete nextMcpServers.askthew;
+    }
+    return {
+        ...existingSettings,
+        mcpServers: {
+            ...nextMcpServers,
+            [input.serverName]: createServerEntry(input),
+        },
+    };
+}
+export function formatInstallCommand(input) {
+    return [
+        "npx",
+        "-y",
+        "@askthew/mcp-plugin@latest",
+        "install",
+        "--host",
+        input.hostType,
+        "--token",
+        JSON.stringify(input.token),
+        "--api-url",
+        JSON.stringify(input.apiUrl),
+        "--server-name",
+        JSON.stringify(input.serverName),
+    ].join(" ");
+}
+export function verificationNextStep(hostType) {
+    const hostLabel = hostType === "claude_code" ? "Claude Code" : "Codex";
+    return `Restart ${hostLabel} if it is already open, then send a setup_complete signal with capture_session_signal. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
+}
+export function installHostConfig(input) {
+    const settingsPath = resolveSettingsPath({
+        hostType: input.hostType,
+        homeDirectory: input.homeDirectory,
+    });
+    let existingSettings = {};
+    if (fs.existsSync(settingsPath)) {
+        const raw = fs.readFileSync(settingsPath, "utf8");
+        if (raw.trim().length > 0) {
+            try {
+                existingSettings = JSON.parse(raw);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : "Unknown parse failure.";
+                throw new Error(`Could not parse existing settings JSON at ${settingsPath}: ${detail}`);
+            }
+        }
+    }
+    const merged = mergeHostSettings({
+        existingSettings,
+        hostType: input.hostType,
+        token: input.token,
+        apiUrl: input.apiUrl,
+        serverName: input.serverName,
+        clientId: input.clientId,
+        clientLabel: input.clientLabel,
+    });
+    const json = JSON.stringify(merged, null, 2);
+    if (!input.dryRun) {
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, `${json}\n`, "utf8");
+    }
+    return {
+        settingsPath,
+        json,
+        wroteFile: !input.dryRun,
+        nextStep: verificationNextStep(input.hostType),
+    };
+}

package/dist/scope.d.ts

@@ -0,0 +1,8 @@
+export interface PluginScope {
+    repoName: string;
+    repoRoot?: string;
+    appPath?: string;
+    serviceName?: string;
+}
+export declare function resolvePluginScope(startDirectory?: string): PluginScope;
+export declare function resolveFunctionalAreaFromToml(startDirectory?: string): string;

package/dist/scope.js

@@ -0,0 +1,60 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+const REPO_MARKERS = [".git", "package.json", "pyproject.toml", "go.mod", "Cargo.toml"];
+function parseAskTheWToml(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    const contents = fs.readFileSync(filePath, "utf8");
+    const readValue = (key) => {
+        const match = contents.match(new RegExp(`${key}\\s*=\\s*["']([^"']+)["']`, "i"));
+        return match?.[1]?.trim() || "";
+    };
+    return {
+        repoName: readValue("repo_name"),
+        repoRoot: readValue("repo_root"),
+        appPath: readValue("app_path"),
+        serviceName: readValue("service_name"),
+        functionalArea: readValue("functional_area"),
+    };
+}
+function findRepoRoot(startDirectory) {
+    let currentDirectory = path.resolve(startDirectory);
+    let highestMarkerDirectory = null;
+    while (true) {
+        if (fs.existsSync(path.join(currentDirectory, ".git"))) {
+            return currentDirectory;
+        }
+        if (REPO_MARKERS.some((marker) => fs.existsSync(path.join(currentDirectory, marker)))) {
+            highestMarkerDirectory = currentDirectory;
+        }
+        const parentDirectory = path.dirname(currentDirectory);
+        if (parentDirectory === currentDirectory) {
+            break;
+        }
+        currentDirectory = parentDirectory;
+    }
+    return highestMarkerDirectory;
+}
+export function resolvePluginScope(startDirectory = process.cwd()) {
+    const cwd = path.resolve(startDirectory);
+    const parsedConfig = parseAskTheWToml(path.join(cwd, ".asktheworld.toml"));
+    const repoRoot = parsedConfig.repoRoot || findRepoRoot(cwd) || cwd;
+    const repoName = parsedConfig.repoName || path.basename(repoRoot);
+    const relativePath = path.relative(repoRoot, cwd);
+    const normalizedRelativePath = relativePath && relativePath !== "." && !relativePath.startsWith("..")
+        ? relativePath.split(path.sep).join("/")
+        : "";
+    const appPath = parsedConfig.appPath || normalizedRelativePath || undefined;
+    return {
+        repoName,
+        repoRoot,
+        ...(appPath ? { appPath } : {}),
+        ...(parsedConfig.serviceName ? { serviceName: parsedConfig.serviceName } : {}),
+    };
+}
+export function resolveFunctionalAreaFromToml(startDirectory = process.cwd()) {
+    const cwd = path.resolve(startDirectory);
+    const parsedConfig = parseAskTheWToml(path.join(cwd, ".asktheworld.toml"));
+    return parsedConfig.functionalArea || "";
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@askthew/mcp-plugin",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Ask The W MCP connector for capturing compact coding-agent session signals.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "askthew-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "README.md",
+    "dist/cli.d.ts",
+    "dist/cli.js",
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/install.d.ts",
+    "dist/install.js",
+    "dist/scope.d.ts",
+    "dist/scope.js"
+  ],
+  "keywords": [
+    "askthew",
+    "mcp",
+    "codex",
+    "claude-code",
+    "cursor",
+    "coding-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./dist/index.js": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "import": "./dist/install.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test dist/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.3.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.2"
+  }
+}