cograph-connect 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Cograph contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/README.md

@@ -0,0 +1,43 @@
+# Cograph Connect
+
+Connect Cograph to local agent clients through MCP and Codex skills.
+
+```bash
+npx -y cograph-connect setup
+```
+
+The setup command stores your Cograph URL and token locally, validates the
+remote `/mcp/` endpoint, and can configure Claude Desktop, Cursor, and Codex
+to launch a local stdio MCP proxy.
+
+## What It Installs
+
+- A local stdio MCP proxy named `cograph`.
+- Client config entries for Claude Desktop, Cursor, and Codex.
+- A Codex skill at `~/.codex/skills/cograph-connect`.
+
+The Cograph token is stored outside client configs:
+
+- macOS/Linux: `~/.config/cograph-connect/config.json`
+- Windows: `%APPDATA%/cograph-connect/config.json`
+
+On POSIX systems the config directory is written as `0700` and the config file
+as `0600`.
+
+## Token Scopes
+
+Create a Cograph personal access token with:
+
+- `mcp`
+- `api:read`
+
+## Commands
+
+```bash
+cograph-connect setup
+cograph-connect status --check
+cograph-connect config print
+cograph-connect mcp --profile default
+```
+
+Use `COGRAPH_CONNECT_TOKEN` to override the stored token for one command.

package/dist/cli.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import prompts from "prompts";
+import { publicConfig, readConfig, redactToken, upsertProfile, } from "./config.js";
+import { configureClient, manualSnippet, } from "./client-config.js";
+import { configPath, packageRoot } from "./paths.js";
+import { validateRemote } from "./remote.js";
+import { installCodexSkill } from "./skill.js";
+import { runMcpProxy } from "./proxy.js";
+const CLIENTS = ["claude", "cursor", "codex"];
+function parseClients(value) {
+    if (!value)
+        return undefined;
+    const parsed = value
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+    for (const client of parsed) {
+        if (!CLIENTS.includes(client)) {
+            throw new Error(`Unknown client: ${client}. Use: ${CLIENTS.join(", ")}`);
+        }
+    }
+    return parsed;
+}
+async function promptMissing(options) {
+    const questions = [];
+    if (!options.url) {
+        questions.push({
+            type: "text",
+            name: "url",
+            message: "Cograph URL",
+            initial: "http://localhost:8080",
+        });
+    }
+    if (!options.token) {
+        questions.push({
+            type: "password",
+            name: "token",
+            message: "Cograph PAT token",
+        });
+    }
+    let selectedClients = parseClients(options.clients);
+    if (!selectedClients && !options.yes) {
+        questions.push({
+            type: "multiselect",
+            name: "clients",
+            message: "Configure agent clients",
+            choices: [
+                { title: "Claude Desktop", value: "claude", selected: true },
+                { title: "Cursor", value: "cursor", selected: true },
+                { title: "Codex", value: "codex", selected: true },
+            ],
+            min: 0,
+        });
+    }
+    const answers = questions.length
+        ? await prompts(questions, {
+            onCancel: () => {
+                throw new Error("Setup cancelled");
+            },
+        })
+        : {};
+    selectedClients =
+        selectedClients || (options.yes ? CLIENTS : (answers.clients ?? []));
+    return {
+        url: options.url || answers.url,
+        token: options.token || answers.token,
+        clients: selectedClients,
+    };
+}
+function printClientResult(result) {
+    const action = result.changed ? "configured" : "already configured";
+    console.log(`${result.client}: ${action} at ${result.path}`);
+    if (result.backupPath) {
+        console.log(`${result.client}: backup written to ${result.backupPath}`);
+    }
+}
+async function runSetup(options) {
+    const resolved = await promptMissing(options);
+    if (!resolved.url || !resolved.token) {
+        throw new Error("Both Cograph URL and token are required");
+    }
+    if (!options.noValidate) {
+        const count = await validateRemote({
+            url: resolved.url,
+            token: resolved.token,
+        });
+        console.log(`Validated remote MCP endpoint. Tools available: ${count}`);
+    }
+    const config = await upsertProfile({
+        profileName: options.profile,
+        url: resolved.url,
+        token: resolved.token,
+    });
+    const profile = config.profiles[options.profile];
+    console.log(`Saved profile "${options.profile}" to ${configPath()}`);
+    console.log(`Token: ${redactToken(profile.token)}`);
+    for (const client of resolved.clients) {
+        try {
+            printClientResult(await configureClient(client, options.profile));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`${client}: could not update config: ${message}`);
+            console.error(`Manual snippet:\n${manualSnippet(client, options.profile)}`);
+        }
+    }
+    if (!options.noSkill) {
+        const target = await installCodexSkill({
+            packageRoot: packageRoot(import.meta.url),
+        });
+        console.log(`codex skill: installed at ${target}`);
+    }
+}
+async function runStatus({ check }) {
+    const config = await readConfig();
+    if (!config) {
+        console.log("cograph-connect is not configured.");
+        return;
+    }
+    console.log(JSON.stringify(publicConfig(config), null, 2));
+    if (check) {
+        const profile = config.profiles[config.defaultProfile];
+        const count = await validateRemote(profile);
+        console.log(`Remote MCP check passed. Tools available: ${count}`);
+    }
+}
+const program = new Command();
+program
+    .name("cograph-connect")
+    .description("Connect Cograph to agent clients through MCP and Codex skills.")
+    .version("0.1.0");
+program
+    .command("setup")
+    .description("Configure Cograph MCP access for local agent clients.")
+    .option("--url <url>", "Cograph base URL or /mcp/ URL")
+    .option("--token <token>", "Cograph PAT token")
+    .option("--profile <name>", "Profile name", "default")
+    .option("--clients <list>", "Comma-separated clients: claude,cursor,codex")
+    .option("-y, --yes", "Use defaults for unanswered choices")
+    .option("--no-validate", "Skip remote MCP validation")
+    .option("--no-skill", "Skip Codex skill installation")
+    .action(async (options) => runSetup(options));
+program
+    .command("mcp")
+    .description("Run the local stdio MCP proxy.")
+    .option("--profile <name>", "Profile name")
+    .action(async ({ profile }) => runMcpProxy(profile));
+program
+    .command("status")
+    .description("Print configured profiles with redacted tokens.")
+    .option("--check", "Validate the default profile against remote Cograph")
+    .action(async (options) => runStatus(options));
+program
+    .command("config")
+    .description("Config utilities.")
+    .command("print")
+    .description("Print cograph-connect config with redacted tokens.")
+    .action(async () => runStatus({ check: false }));
+program.parseAsync().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message.replace(/Bearer\s+\S+/gi, "Bearer <redacted>"));
+    process.exitCode = 1;
+});

package/dist/client-config.js

@@ -0,0 +1,95 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { clientConfigPath } from "./paths.js";
+export const MCP_SERVER_NAME = "cograph";
+export function mcpServerConfig(profile = "default") {
+    return {
+        command: "npx",
+        args: ["-y", "cograph-connect", "mcp", "--profile", profile],
+    };
+}
+async function backupIfExists(filePath) {
+    try {
+        await fs.stat(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const backupPath = `${filePath}.bak.${new Date()
+        .toISOString()
+        .replace(/[:.]/g, "-")}`;
+    await fs.copyFile(filePath, backupPath);
+    return backupPath;
+}
+async function readTextIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function mergeJsonMcpConfig(raw, profile) {
+    const parsed = raw?.trim() ? JSON.parse(raw) : {};
+    const root = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    const record = root;
+    const existingServers = record.mcpServers &&
+        typeof record.mcpServers === "object" &&
+        !Array.isArray(record.mcpServers)
+        ? record.mcpServers
+        : {};
+    record.mcpServers = {
+        ...existingServers,
+        [MCP_SERVER_NAME]: mcpServerConfig(profile),
+    };
+    return `${JSON.stringify(record, null, 2)}\n`;
+}
+export function mergeCodexTomlConfig(raw, profile) {
+    const lines = (raw ?? "").split(/\r?\n/);
+    const output = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (/^\s*\[mcp_servers\.cograph\]\s*$/.test(line)) {
+            skipping = true;
+            continue;
+        }
+        if (skipping && /^\s*\[/.test(line)) {
+            skipping = false;
+        }
+        if (!skipping) {
+            output.push(line);
+        }
+    }
+    while (output.length > 0 && output[output.length - 1] === "") {
+        output.pop();
+    }
+    const block = [
+        "[mcp_servers.cograph]",
+        'command = "npx"',
+        `args = ["-y", "cograph-connect", "mcp", "--profile", ${JSON.stringify(profile)}]`,
+    ];
+    return `${output.length ? `${output.join("\n")}\n\n` : ""}${block.join("\n")}\n`;
+}
+export async function configureClient(client, profile, filePath = clientConfigPath(client)) {
+    const raw = await readTextIfExists(filePath);
+    const next = client === "codex"
+        ? mergeCodexTomlConfig(raw, profile)
+        : mergeJsonMcpConfig(raw, profile);
+    if (raw === next) {
+        return { client, path: filePath, changed: false };
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const backupPath = await backupIfExists(filePath);
+    await fs.writeFile(filePath, next, "utf8");
+    return { client, path: filePath, changed: true, backupPath };
+}
+export function manualSnippet(client, profile = "default") {
+    if (client === "codex") {
+        return mergeCodexTomlConfig("", profile).trimEnd();
+    }
+    return JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: mcpServerConfig(profile) } }, null, 2);
+}

package/dist/config.js

@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { configPath } from "./paths.js";
+export function normalizeMcpUrl(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error("Cograph URL is required");
+    }
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
+        ? trimmed
+        : `http://${trimmed}`;
+    const url = new URL(withScheme);
+    if (url.pathname === "/" || url.pathname === "") {
+        url.pathname = "/mcp/";
+    }
+    else if (url.pathname.endsWith("/mcp")) {
+        url.pathname = `${url.pathname}/`;
+    }
+    else if (!url.pathname.endsWith("/mcp/")) {
+        url.pathname = path.posix.join(url.pathname, "mcp/");
+        if (!url.pathname.endsWith("/")) {
+            url.pathname = `${url.pathname}/`;
+        }
+    }
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}
+export function redactToken(token) {
+    if (!token)
+        return "";
+    if (token.length <= 16)
+        return `${token.slice(0, 4)}…`;
+    return `${token.slice(0, 12)}…${token.slice(-6)}`;
+}
+export async function readConfig(filePath = configPath()) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.version !== 1 || typeof parsed.defaultProfile !== "string") {
+            throw new Error("Unsupported cograph-connect config format");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeConfig(config, filePath = configPath()) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const body = `${JSON.stringify(config, null, 2)}\n`;
+    await fs.writeFile(filePath, body, { mode: 0o600 });
+    if (process.platform !== "win32") {
+        await fs.chmod(path.dirname(filePath), 0o700).catch(() => undefined);
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+}
+export async function upsertProfile({ profileName, url, token, filePath = configPath(), }) {
+    const existing = await readConfig(filePath);
+    const now = new Date().toISOString();
+    const config = existing ?? { version: 1, defaultProfile: profileName, profiles: {} };
+    const previous = config.profiles[profileName];
+    config.defaultProfile = profileName;
+    config.profiles[profileName] = {
+        url: normalizeMcpUrl(url),
+        token,
+        createdAt: previous?.createdAt ?? now,
+        updatedAt: now,
+    };
+    await writeConfig(config, filePath);
+    return config;
+}
+export function publicConfig(config) {
+    return {
+        version: config.version,
+        defaultProfile: config.defaultProfile,
+        profiles: Object.fromEntries(Object.entries(config.profiles).map(([name, profile]) => [
+            name,
+            {
+                url: profile.url,
+                token: redactToken(profile.token),
+                createdAt: profile.createdAt,
+                updatedAt: profile.updatedAt,
+            },
+        ])),
+    };
+}
+export async function requireProfile(profileName) {
+    const config = await readConfig();
+    if (!config) {
+        throw new Error("cograph-connect is not configured. Run `cograph-connect setup`.");
+    }
+    const name = profileName || config.defaultProfile;
+    const profile = config.profiles[name];
+    if (!profile) {
+        throw new Error(`Profile not found: ${name}`);
+    }
+    return {
+        ...profile,
+        token: process.env.COGRAPH_CONNECT_TOKEN || profile.token,
+    };
+}

package/dist/paths.js

@@ -0,0 +1,38 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export function configPath() {
+    if (process.env.COGRAPH_CONNECT_CONFIG) {
+        return path.resolve(process.env.COGRAPH_CONNECT_CONFIG);
+    }
+    if (process.platform === "win32") {
+        const base = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(base, "cograph-connect", "config.json");
+    }
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    return path.join(base, "cograph-connect", "config.json");
+}
+export function clientConfigPath(client) {
+    const home = os.homedir();
+    switch (client) {
+        case "claude":
+            if (process.platform === "darwin") {
+                return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+            }
+            if (process.platform === "win32") {
+                const base = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+                return path.join(base, "Claude", "claude_desktop_config.json");
+            }
+            return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+        case "cursor":
+            return path.join(home, ".cursor", "mcp.json");
+        case "codex":
+            return path.join(home, ".codex", "config.toml");
+    }
+}
+export function codexSkillPath() {
+    return path.join(os.homedir(), ".codex", "skills", "cograph-connect");
+}
+export function packageRoot(metaUrl) {
+    return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..");
+}

package/dist/proxy.js

@@ -0,0 +1,43 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { requireProfile } from "./config.js";
+import { closeRemote, connectRemote } from "./remote.js";
+function proxiedCapabilities(client) {
+    const remote = client.getServerCapabilities();
+    const capabilities = {};
+    if (remote?.tools)
+        capabilities.tools = {};
+    if (remote?.resources)
+        capabilities.resources = {};
+    if (remote?.prompts)
+        capabilities.prompts = {};
+    return capabilities;
+}
+export async function runMcpProxy(profileName) {
+    const profile = await requireProfile(profileName);
+    let remote;
+    try {
+        remote = await connectRemote(profile);
+        const server = new Server({ name: "cograph", version: "0.1.0" }, {
+            capabilities: proxiedCapabilities(remote.client),
+            instructions: remote.client.getInstructions() ||
+                "Use Cograph to query indexed repositories, wiki pages, graph context, and markdown collections.",
+        });
+        server.setRequestHandler(ListToolsRequestSchema, (request) => remote.client.listTools(request.params));
+        server.setRequestHandler(CallToolRequestSchema, (request) => remote.client.callTool(request.params));
+        server.setRequestHandler(ListResourcesRequestSchema, (request) => remote.client.listResources(request.params));
+        server.setRequestHandler(ListResourceTemplatesRequestSchema, (request) => remote.client.listResourceTemplates(request.params));
+        server.setRequestHandler(ReadResourceRequestSchema, (request) => remote.client.readResource(request.params));
+        server.setRequestHandler(ListPromptsRequestSchema, (request) => remote.client.listPrompts(request.params));
+        server.setRequestHandler(GetPromptRequestSchema, (request) => remote.client.getPrompt(request.params));
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`cograph-connect MCP proxy failed: ${message}\n`);
+        await (remote ? closeRemote(remote) : Promise.resolve());
+        process.exitCode = 1;
+    }
+}

package/dist/remote.js

@@ -0,0 +1,29 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { normalizeMcpUrl } from "./config.js";
+export async function connectRemote({ url, token, }) {
+    const transport = new StreamableHTTPClientTransport(new URL(normalizeMcpUrl(url)), {
+        requestInit: {
+            headers: new Headers({
+                Authorization: `Bearer ${token}`,
+            }),
+        },
+    });
+    const client = new Client({ name: "cograph-connect", version: "0.1.0" }, { capabilities: {} });
+    await client.connect(transport);
+    return { client, transport };
+}
+export async function closeRemote(connection) {
+    await connection.transport.terminateSession().catch(() => undefined);
+    await connection.client.close().catch(() => undefined);
+}
+export async function validateRemote({ url, token, }) {
+    const connection = await connectRemote({ url, token });
+    try {
+        const result = await connection.client.listTools();
+        return result.tools.length;
+    }
+    finally {
+        await closeRemote(connection);
+    }
+}

package/dist/skill.js

@@ -0,0 +1,10 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { codexSkillPath } from "./paths.js";
+export async function installCodexSkill({ packageRoot, target = codexSkillPath(), }) {
+    const source = path.join(packageRoot, "templates", "codex-skill");
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.rm(target, { recursive: true, force: true });
+    await fs.cp(source, target, { recursive: true });
+    return target;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "cograph-connect",
+  "version": "0.1.0",
+  "description": "Connect Cograph to agent clients through MCP and Codex skills.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "cograph-connect": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.2",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/prompts": "^2.4.9",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikekonan/cograph-connect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mikekonan/cograph-connect/issues"
+  },
+  "homepage": "https://github.com/mikekonan/cograph-connect#readme"
+}

package/templates/codex-skill/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: cograph-connect
+description: Use Cograph MCP when answering questions about indexed repositories, generated wiki pages, code search, markdown collections, architecture, or project documentation available through Cograph.
+---
+
+# Cograph Connect
+
+Use the configured Cograph MCP server for questions about indexed repositories,
+generated wiki pages, code graph context, markdown collections, architecture,
+and project documentation.
+
+## Workflow
+
+- Start by listing available repositories or collections when the target is not explicit.
+- Prefer precise Cograph tools/resources over broad filesystem or web searches.
+- Preserve provenance from Cograph responses in your answer when available.
+- If Cograph returns an authorization error, ask the user to run `cograph-connect setup` with a token that has `mcp` and `api:read` scopes.