@aipermission/mcp 0.1.0

package/dist/install-skill.js

@@ -0,0 +1,209 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILL_NAME = "aipermission-operator";
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+export async function runInstallSkill(argv = []) {
+  const flags = parseFlags(argv);
+  const client = normalizeClient(flags.client || "codex");
+  const skill = await loadSkill(flags.source);
+  const homeDir = flags.home || os.homedir();
+  const projectDir = flags.projectDir || process.cwd();
+
+  if (client === "custom") {
+    console.log(renderInstruction("custom", skill));
+    return;
+  }
+
+  const targetPath = skillPathForClient(client, { homeDir, projectDir });
+  const content = renderInstruction(client, skill);
+  if (client === "gemini") {
+    await upsertMarkedSection(targetPath, content);
+  } else {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content, { mode: 0o644 });
+  }
+
+  console.log(`Installed ${SKILL_NAME} instructions for ${clientLabel(client)}:`);
+  console.log(targetPath);
+  console.log("");
+  console.log("Restart the AI client or open a new session so the instructions refresh.");
+}
+
+export function codexSkillPath(homeDir) {
+  return path.join(homeDir, ".codex", "skills", SKILL_NAME, "SKILL.md");
+}
+
+export function skillPathForClient(client, { homeDir = os.homedir(), projectDir = process.cwd() } = {}) {
+  const normalized = normalizeClient(client);
+  if (normalized === "codex") {
+    return codexSkillPath(homeDir);
+  }
+  if (normalized === "claude-code") {
+    return path.join(projectDir, ".claude", "rules", `${SKILL_NAME}.md`);
+  }
+  if (normalized === "cursor") {
+    return path.join(projectDir, ".cursor", "rules", `${SKILL_NAME}.mdc`);
+  }
+  if (normalized === "vscode") {
+    return path.join(projectDir, ".github", "instructions", `${SKILL_NAME}.instructions.md`);
+  }
+  if (normalized === "windsurf") {
+    return path.join(projectDir, ".windsurf", "rules", `${SKILL_NAME}.md`);
+  }
+  if (normalized === "antigravity") {
+    return path.join(projectDir, ".agents", "rules", `${SKILL_NAME}.md`);
+  }
+  if (normalized === "gemini") {
+    return path.join(projectDir, "GEMINI.md");
+  }
+  throw new Error(`Unsupported client: ${client}`);
+}
+
+export async function loadSkill(source) {
+  if (source) {
+    return readSkillSource(source);
+  }
+  const errors = [];
+  for (const candidate of bundledSkillCandidates()) {
+    try {
+      return await readSkillSource(candidate);
+    } catch (error) {
+      errors.push(`${candidate}: ${error.message}`);
+    }
+  }
+  throw new Error(`Could not load bundled ${SKILL_NAME} skill.\n${errors.join("\n")}`);
+}
+
+function bundledSkillCandidates() {
+  return [
+    path.join(moduleDir, "resources", SKILL_NAME, "SKILL.md"),
+    path.join(moduleDir, "..", "resources", SKILL_NAME, "SKILL.md"),
+  ];
+}
+
+async function readSkillSource(source) {
+  if (/^https?:\/\//i.test(source)) {
+    throw new Error("remote skill sources are not supported; use the bundled skill or a local file path");
+  }
+  return validateSkill(await fs.readFile(source, "utf8"));
+}
+
+function validateSkill(value) {
+  if (!value.includes(`name: ${SKILL_NAME}`)) {
+    throw new Error(`source does not look like ${SKILL_NAME}`);
+  }
+  return value;
+}
+
+export function renderInstruction(client, skill) {
+  const normalized = normalizeClient(client);
+  if (normalized === "codex") {
+    return skill;
+  }
+
+  const body = stripSkillFrontmatter(skill).trim();
+  if (normalized === "claude-code") {
+    return `${body}\n`;
+  }
+  if (normalized === "cursor") {
+    return `---\ndescription: AIPermission MCP operator workflow for approval polling, console reads, reasons, and secret-safe commands.\nglobs:\nalwaysApply: true\n---\n\n${body}\n`;
+  }
+  if (normalized === "vscode") {
+    return `---\nname: AIPermission Operator\ndescription: Use AIPermission MCP safely with approvals, console reads, reasons, and secret hygiene.\napplyTo: "**"\n---\n\n${body}\n`;
+  }
+  if (normalized === "windsurf") {
+    return `---\ntrigger: always_on\n---\n\n${body}\n`;
+  }
+  if (normalized === "antigravity") {
+    return `---\ndescription: AIPermission MCP operator workflow\ntrigger: always_on\n---\n\n${body}\n`;
+  }
+  if (normalized === "gemini") {
+    return `## AIPermission Operator\n\n${body.replace(/^# AIPermission Operator\s*/m, "").trim()}\n`;
+  }
+  if (normalized === "custom") {
+    return `${body}\n`;
+  }
+  throw new Error(`Unsupported client: ${client}`);
+}
+
+export function normalizeClient(value) {
+  const client = String(value || "").trim().toLowerCase();
+  const aliases = {
+    claude: "claude-code",
+    "claude_code": "claude-code",
+    "claude-code": "claude-code",
+    copilot: "vscode",
+    "vs-code": "vscode",
+    "google-antigravity": "antigravity",
+    agy: "antigravity",
+    "gemini-cli": "gemini",
+  };
+  const normalized = aliases[client] || client;
+  const supported = new Set(["codex", "claude-code", "cursor", "vscode", "windsurf", "antigravity", "gemini", "custom"]);
+  if (!supported.has(normalized)) {
+    throw new Error(`Unknown client: ${value}`);
+  }
+  return normalized;
+}
+
+function clientLabel(client) {
+  return {
+    codex: "Codex",
+    "claude-code": "Claude Code",
+    cursor: "Cursor",
+    vscode: "VS Code / GitHub Copilot",
+    windsurf: "Windsurf",
+    antigravity: "Google Antigravity",
+    gemini: "Gemini CLI",
+    custom: "Custom",
+  }[client] || client;
+}
+
+function stripSkillFrontmatter(value) {
+  return value.replace(/^---\n[\s\S]*?\n---\n?/, "");
+}
+
+async function upsertMarkedSection(filePath, content) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const start = "<!-- aipermission-operator:start -->";
+  const end = "<!-- aipermission-operator:end -->";
+  const section = `${start}\n${content.trim()}\n${end}\n`;
+  let existing = "";
+  try {
+    existing = await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\n?`);
+  const next = pattern.test(existing)
+    ? existing.replace(pattern, section)
+    : `${existing.replace(/\s*$/, "")}${existing.trim() ? "\n\n" : ""}${section}`;
+  await fs.writeFile(filePath, next, { mode: 0o644 });
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function parseFlags(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    result[key] = inlineValue ?? argv[i + 1] ?? "";
+    if (inlineValue === undefined) {
+      i += 1;
+    }
+  }
+  return result;
+}

package/dist/local-url.js

@@ -0,0 +1,27 @@
+export const DEFAULT_API_URL = "http://localhost:3210";
+
+const allowedLocalHosts = new Set(["localhost", "127.0.0.1", "::1"]);
+
+export function normalizeLocalAPIURL(value = DEFAULT_API_URL) {
+  const raw = String(value || DEFAULT_API_URL).trim();
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error("AIPERMISSION_API_URL must be a valid local HTTP URL.");
+  }
+  if (parsed.protocol !== "http:") {
+    throw new Error("AIPERMISSION_API_URL must use http:// for the local gateway.");
+  }
+  let hostname = parsed.hostname.toLowerCase();
+  if (hostname === "[::1]") {
+    hostname = "::1";
+  }
+  if (!allowedLocalHosts.has(hostname)) {
+    throw new Error("AIPERMISSION_API_URL must point to localhost, 127.0.0.1, or [::1].");
+  }
+  if ((parsed.pathname && parsed.pathname !== "/") || parsed.search || parsed.hash) {
+    throw new Error("AIPERMISSION_API_URL must be the gateway origin only, for example http://localhost:3210.");
+  }
+  return parsed.toString().replace(/\/$/, "");
+}

package/dist/resources/aipermission-operator/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: aipermission-operator
+description: Use when operating servers through the AIPermission MCP gateway. Guides AI agents to handle approval_pending/running states, poll get_request, read live console output, write short reasons, avoid leaking secrets, and keep command execution safe and auditable.
+---
+
+# AIPermission Operator
+
+## Core Rule
+
+Use AIPermission as a local, developer-controlled execution gateway.
+
+You are allowed to operate only the servers returned by `list_servers()`. Do not ask for SSH passwords, private keys, database passwords, or raw credentials. The gateway owns credentials, permissions, approvals, console sessions, and audit history.
+
+AIPermission is not a general DevOps control plane. Treat it as a temporary, scoped maintenance/debugging channel controlled by the human operator.
+
+## Initial Discovery
+
+Before executing commands:
+
+1. Call `list_servers()`.
+2. Read each server's `name`, `id`, `execution_rule`, and `hints`.
+3. Use the numeric `id` returned by the tool.
+4. Pick the narrowest server set that can answer the task.
+
+If no server is visible, say that the current token has no accessible servers.
+
+## Command Reasons
+
+Every `exec` call should include a short `reason`.
+
+Good reasons:
+
+```text
+Check Docker service state before cleanup.
+Inspect recent kubelet errors on worker node.
+Verify trial worker deployment after node label change.
+```
+
+Avoid vague reasons:
+
+```text
+run command
+debug
+test
+```
+
+## Approval Flow
+
+`approval_pending` is not terminal.
+
+When `exec` returns `approval_pending`:
+
+1. Read `retry_after_seconds`; default to 3 seconds if missing.
+2. Wait that long.
+3. Call `get_request(request_id)`.
+4. Continue polling until the status is terminal.
+5. If status becomes `running`, keep polling `get_request(request_id)`; `read_console` is only available when the token has `always_run` permission for that server.
+
+Terminal statuses:
+
+```text
+completed
+failed
+declined
+blocked
+error
+```
+
+If the request is `declined`, read `user_note` and follow the user's correction.
+
+## Running Flow
+
+When `exec` or `get_request` returns `running`:
+
+1. If the server permission is `always_run`, call `read_console(server_id)` before sending another long-running command to the same server.
+2. Poll `get_request(request_id)` every 3-5 seconds.
+3. Use `read_console(server_id)` between polls only when the token has `always_run` permission.
+4. Do not start another long-running command on the same server until the active request reaches a terminal status, unless the user explicitly asks.
+
+## Message Flow
+
+Use `send_message(message, server_id?, session_id?)` for short operator-visible notes.
+
+Good messages:
+
+```text
+Docker install started; waiting for package installation to finish.
+K3s agent joined. Checking node labels now.
+The command is still running; reading console output before next step.
+```
+
+When a response includes `user_note`, treat it as live operator guidance. Apply it before continuing.
+
+## Safe Shell Practice
+
+Prefer commands that are:
+
+- non-interactive
+- bounded in output
+- explicit about destructive actions
+- easy to audit from history
+
+MCP `exec` closes stdin for the command body. Do not use commands that wait for interactive stdin. Use flags such as `-y`, `--no-pager`, heredoc-created files, or the manual web console for interactive work.
+
+Use examples like:
+
+```sh
+systemctl is-active docker
+journalctl --no-pager -u k3s-agent -n 100
+docker logs --tail 100 CONTAINER
+kubectl get nodes -o wide
+df -h
+free -m
+```
+
+For apt on Debian/Ubuntu:
+
+```sh
+export DEBIAN_FRONTEND=noninteractive
+apt-get update
+apt-get install -y PACKAGE
+```
+
+After install/uninstall checks in the same shell, refresh command lookup:
+
+```sh
+hash -r 2>/dev/null || true
+```
+
+For package verification, prefer installed-state checks over ambiguous removed-package residue:
+
+```sh
+dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package} ${Version}\n' docker-ce docker-ce-cli 2>/dev/null | grep '^ii'
+```
+
+## Output Hygiene
+
+Avoid huge unbounded output.
+
+Prefer:
+
+```sh
+tail -n 100 /path/to/log
+journalctl --no-pager -n 100
+docker logs --tail 100 NAME
+kubectl logs --tail=100 POD
+```
+
+Avoid:
+
+```sh
+cat huge.log
+journalctl
+docker logs NAME
+```
+
+## Secret Hygiene
+
+Command text, command output, history, audit records, and console transcript may be stored in the encrypted local database.
+
+Do not print secrets unless the user explicitly asks and accepts the risk. Avoid commands that dump:
+
+- private keys
+- `.env` files
+- token files
+- database passwords
+- cloud credentials
+- Kubernetes secrets
+
+Prefer existence and metadata checks:
+
+```sh
+test -f /path/to/.env && echo exists
+ls -l /path/to/secret-file
+kubectl get secret NAME -o jsonpath='{.metadata.name}'
+```
+
+## Destructive Actions
+
+Before destructive actions:
+
+1. Inspect current state.
+2. Explain the exact destructive command in the `reason`.
+3. Prefer one clear destructive step at a time.
+4. Verify after completion.
+
+Examples of destructive actions:
+
+- deleting containers, volumes, images
+- uninstalling packages
+- removing files
+- restarting critical services
+- changing Kubernetes labels or draining nodes
+
+## Multi-Server Work
+
+For multiple servers:
+
+1. Check visibility with `list_servers()`.
+2. Work one risky operation at a time.
+3. Keep each command targeted to one server unless the user explicitly requests batch behavior.
+4. Summarize per-server status after each phase.
+
+## Final Response
+
+When reporting back to the user, include:
+
+- servers touched
+- commands or command groups run
+- important findings
+- changes made
+- verification results
+- any pending/recommended next steps
+
+Keep it concise and operational.

package/dist/results.js

@@ -0,0 +1,32 @@
+export function textResult(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+export function errorResult(error) {
+  const message = error instanceof Error ? error.message : String(error || "Unknown aipermission MCP error");
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ status: "error", error: message }, null, 2),
+      },
+    ],
+  };
+}
+
+export async function jsonToolResult(callback) {
+  try {
+    return textResult(await callback());
+  } catch (error) {
+    return errorResult(error);
+  }
+}

package/dist/server.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+if (process.argv[2] === "init") {
+  const { runInit } = await import("./init.js");
+  await runInit(process.argv.slice(3));
+  process.exit(0);
+}
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { normalizeLocalAPIURL } from "./local-url.js";
+import { jsonToolResult } from "./results.js";
+
+const apiUrl = normalizeLocalAPIURL(process.env.AIPERMISSION_API_URL);
+const apiToken = process.env.AIPERMISSION_API_TOKEN || "";
+const apiTimeoutMs = Number.parseInt(process.env.AIPERMISSION_HTTP_TIMEOUT_MS || "60000", 10);
+
+const server = new McpServer({
+  name: "aipermission",
+  version: "0.1.0",
+});
+
+server.tool(
+  "list_servers",
+  "List servers this aipermission token can access. Credentials are never returned.",
+  {},
+  async () => {
+    return jsonToolResult(() => apiGet("/api/mcp/servers"));
+  }
+);
+
+server.tool(
+  "exec",
+  "Execute a shell command on an allowed server through the local aipermission gateway. If status is approval_pending, follow assistant_hint and poll get_request. Long always_run commands return running; use read_console to continue watching.",
+  {
+    server_id: z.number().int().positive().describe("Server id from list_servers."),
+    command: z.string().min(1).describe("Shell command to execute."),
+    reason: z.string().optional().describe("Why this command is needed."),
+  },
+  async ({ server_id, command, reason }) => {
+    return jsonToolResult(() => apiPost("/api/mcp/exec", {
+      server_id,
+      command,
+      reason: reason || "",
+    }));
+  }
+);
+
+server.tool(
+  "read_console",
+  "Read the latest persistent console transcript for an allowed server. Use this after a long-running exec returns running.",
+  {
+    server_id: z.number().int().positive().describe("Server id from list_servers."),
+    tail: z.number().int().positive().max(100000).optional().describe("Maximum transcript characters to return."),
+  },
+  async ({ server_id, tail }) => {
+    return jsonToolResult(() => {
+      const params = new URLSearchParams({ server_id: String(server_id) });
+      if (tail) {
+        params.set("tail", String(tail));
+      }
+      return apiGet(`/api/mcp/console?${params.toString()}`);
+    });
+  }
+);
+
+server.tool(
+  "get_request",
+  "Read an aipermission command request by id. Use this after exec returns approval_pending or running.",
+  {
+    request_id: z.number().int().positive().describe("Request id returned by exec."),
+  },
+  async ({ request_id }) => {
+    return jsonToolResult(() => apiGet(`/api/mcp/requests/${request_id}`));
+  }
+);
+
+server.tool(
+  "list_requests",
+  "List command requests for this token. Optionally filter by status such as pending_approval, running, completed, failed, declined, or error.",
+  {
+    status: z.string().optional().describe("Optional request status filter."),
+  },
+  async ({ status }) => {
+    return jsonToolResult(() => {
+      const params = new URLSearchParams();
+      if (status) {
+        params.set("status", status);
+      }
+      const suffix = params.toString() ? `?${params.toString()}` : "";
+      return apiGet(`/api/mcp/requests${suffix}`);
+    });
+  }
+);
+
+server.tool(
+  "send_message",
+  "Send a short note to the aipermission Console messages panel for the human operator.",
+  {
+    message: z.string().min(1).describe("Message to show in the Console messages panel."),
+    server_id: z.number().int().positive().optional().describe("Optional server id this message is about."),
+    session_id: z.number().int().positive().optional().describe("Optional console session id this message is about."),
+  },
+  async ({ message, server_id, session_id }) => {
+    return jsonToolResult(() => apiPost("/api/mcp/messages", {
+      message,
+      server_id: server_id || null,
+      session_id: session_id || null,
+    }));
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+async function apiGet(path) {
+  return apiRequest(path, {
+    method: "GET",
+  });
+}
+
+async function apiPost(path, body) {
+  return apiRequest(path, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+async function apiRequest(path, options) {
+  if (!apiToken) {
+    throw new Error("AIPERMISSION_API_TOKEN is required.");
+  }
+  const timeout = Number.isFinite(apiTimeoutMs) && apiTimeoutMs > 0 ? apiTimeoutMs : 60000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  let response;
+  try {
+    response = await fetch(`${apiUrl}${path}`, {
+      ...options,
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiToken}`,
+        ...(options.headers || {}),
+      },
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error(`aipermission API request timed out after ${timeout}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+  const text = await response.text();
+  const data = parseResponseBody(text);
+  if (!response.ok) {
+    throw new Error(data?.error || `aipermission API request failed with ${response.status}`);
+  }
+  return data;
+}
+
+function parseResponseBody(text) {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: text.trim() || "Invalid non-JSON response from aipermission gateway." };
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@aipermission/mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.aipermission/aipermission-mcp",
+  "description": "Local-first MCP bridge for the aipermission gateway.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/aipermission/aipermission/tree/main/packages/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aipermission/aipermission.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/aipermission/aipermission/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "aipermission-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepack": "npm run build",
+    "test": "node --test test/*.test.js",
+    "start": "node dist/cli.js",
+    "dev": "node src/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "3.25.76"
+  }
+}