The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
import fs from "node:fs/promises";
import { constants } from "node:fs";
import path from "node:path";
import { DatabaseSync } from "node:sqlite";
import { createHash, randomUUID } from "node:crypto";
import { setTimeout as sleep } from "node:timers/promises";
import { PUBLIC_MCP_PATH, PUBLIC_MCP_SCOPES } from "@paperclipai/shared";
import { resolvePaperclipHomeDir } from "../config/home.js";
const deviceGrant = "urn:ietf:params:oauth:grant-type:device_code";
type Json = Record<string, unknown>;
export interface McpCredential {
resource: string; issuer: string; clientId: string; companyId: string;
accessToken: string; refreshToken?: string; expiresAt: number;
}
export function mcpResource(raw: string) {
const url = new URL(raw);
if ((url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
|| url.username || url.password || url.search || url.hash || url.pathname !== PUBLIC_MCP_PATH) throw new Error("Use the exact Paperclip HTTPS MCP URL from Connections.");
return url.toString();
}
export function credentialPath(resource: string) {
return path.join(resolvePaperclipHomeDir(), "mcp", createHash("sha256").update(resource).digest("hex") + ".json");
}
async function readCredential(file: string): Promise<McpCredential | null> {
let handle;
try { handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW); }
catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
try {
const stat = await handle.stat();
if (!stat.isFile() || (stat.mode & 0o077) !== 0) throw new Error("MCP credential file must be private (mode 0600).");
let value: McpCredential;
try { value = JSON.parse(await handle.readFile("utf8")); }
catch { throw new Error("Invalid MCP credential file. Sign in again."); }
if (!value || typeof value !== "object" || ![value.resource, value.issuer, value.clientId, value.companyId, value.accessToken].every(v => typeof v === "string" && v.length > 0)
|| !Number.isFinite(value.expiresAt) || (value.refreshToken !== undefined && typeof value.refreshToken !== "string")) throw new Error("Invalid MCP credential file. Sign in again.");
return value;
} finally { await handle.close(); }
}
async function saveCredential(file: string, credential: McpCredential) {
const temporary = file + "." + randomUUID();
try {
await fs.writeFile(temporary, JSON.stringify(credential), { mode: 0o600, flag: "wx" });
await fs.rename(temporary, file);
} finally { await fs.unlink(temporary).catch(() => {}); }
}
/** One refresh owner per resource, including independent CLI/bridge processes. */
const processLocks = new Map<string, Promise<void>>();
export async function withMcpCredentialLock<T>(file: string, work: () => Promise<T>) {
const key = path.resolve(file);
const previous = processLocks.get(key) ?? Promise.resolve();
let release!: () => void;
const current = new Promise<void>(resolve => { release = resolve; });
processLocks.set(key, current);
await previous;
try { return await withMcpOsLock(key, work); }
finally {
release();
if (processLocks.get(key) === current) processLocks.delete(key);
}
}
async function withMcpOsLock<T>(file: string, work: () => Promise<T>) {
const directory = path.dirname(file);
await fs.mkdir(directory, { recursive: true, mode: 0o700 });
const stat = await fs.lstat(directory);
if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) throw new Error("The MCP credential directory must be private (mode 0700).");
// SQLite's OS lock is released when a process exits, including during acquisition.
// No PID-file deletion or stale-lock takeover can race a new refresh owner.
const lockPath = file + ".mutex.sqlite";
// Never open/close an existing SQLite file outside SQLite: POSIX close can
// release another connection's process-owned lock. The in-process queue also
// serializes initial file creation before any SQLite descriptor is opened.
try {
await fs.writeFile(lockPath, "", { flag: "wx", mode: 0o600 });
} catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
const lockStat = await fs.lstat(lockPath);
if (!lockStat.isFile() || lockStat.isSymbolicLink() || (lockStat.mode & 0o077) !== 0) throw new Error("The MCP mutex file must be private (mode 0600).");
const lock = new DatabaseSync(lockPath);
const deadline = Date.now() + 30_000;
try {
lock.exec("PRAGMA busy_timeout = 0");
while (true) {
try { lock.exec("BEGIN IMMEDIATE"); break; }
catch (error) {
if ((error as { errcode?: number }).errcode !== 5) throw error;
if (Date.now() >= deadline) throw new Error("Another Paperclip MCP login or refresh is in progress. Try again.");
await sleep(100);
}
}
try { return await work(); }
finally { lock.exec("ROLLBACK"); }
} finally { lock.close(); }
}
async function jsonRequest(url: string, body?: Json) {
const response = await fetch(url, { redirect: "error", signal: AbortSignal.timeout(20_000),
...(body ? { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) } : {}) });
const data = await safeJson(response);
return { ok: response.ok, data };
}
async function safeJson(response: Response): Promise<Json> {
try {
const value = await response.json();
if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error();
return value as Json;
} catch { throw new Error("Paperclip returned an invalid response. Check the connection before retrying."); }
}
async function revoke(credential: McpCredential) {
const response = await fetch(credential.issuer + "/mcp/oauth/revoke", { method: "POST", redirect: "error", signal: AbortSignal.timeout(20_000),
headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_id: credential.clientId, token: credential.refreshToken ?? credential.accessToken }) });
if (!response.ok) throw new Error("Could not revoke the previous connection.");
}
async function discovery(resource: string) {
const origin = new URL(resource).origin;
const protectedResource = await jsonRequest(origin + "/.well-known/oauth-protected-resource" + PUBLIC_MCP_PATH);
if (!protectedResource.ok || protectedResource.data.resource !== resource || !Array.isArray(protectedResource.data.authorization_servers)
|| !protectedResource.data.authorization_servers.includes(origin)) throw new Error("Paperclip resource discovery does not match this instance.");
const metadata = await jsonRequest(origin + "/.well-known/oauth-authorization-server");
if (!metadata.ok || metadata.data.issuer !== origin || metadata.data.token_endpoint !== origin + "/mcp/oauth/token"
|| metadata.data.device_authorization_endpoint !== origin + "/mcp/oauth/device_authorization"
|| metadata.data.registration_endpoint !== origin + "/mcp/oauth/register") throw new Error("This Paperclip instance does not support device login.");
return origin;
}
function tokens(data: Json, credential: Omit<McpCredential, "accessToken" | "expiresAt">): McpCredential {
if (typeof data.access_token !== "string" || data.token_type !== "Bearer" || typeof data.expires_in !== "number" || data.expires_in <= 0) throw new Error("Invalid Paperclip token response. Reconnect.");
return { ...credential, accessToken: data.access_token, expiresAt: Date.now() + data.expires_in * 1000,
...(typeof data.refresh_token === "string" ? { refreshToken: data.refresh_token } : {}) };
}
export async function mcpRpc(resource: string, token: string, method: string, params: Json = {}) {
const version = "2026-07-28";
const response = await fetch(resource, { method: "POST", redirect: "error", signal: AbortSignal.timeout(60_000),
headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "MCP-Protocol-Version": version, "Mcp-Method": method,
...(method === "tools/call" && typeof params.name === "string" ? { "Mcp-Name": params.name } : {}) },
body: JSON.stringify({ jsonrpc: "2.0", id: randomUUID(), method, params: { ...params, _meta: {
"io.modelcontextprotocol/protocolVersion": version, "io.modelcontextprotocol/clientCapabilities": {},
"io.modelcontextprotocol/clientInfo": { name: "Paperclip CLI", version: "1" },
} } }),
});
if (!response.ok) throw new Error(`Paperclip MCP returned HTTP ${response.status}. Check the connection before retrying; a write may already have completed.`);
const data = await safeJson(response);
if (data.error || !data.result || typeof data.result !== "object") throw new Error("Paperclip could not complete this MCP request. Check the connection before retrying.");
return data.result as Json;
}
export async function loginMcpDevice(raw: string, companyId?: string, notify: (message: string) => void = console.error) {
const resource = mcpResource(raw);
const issuer = await discovery(resource);
const registration = await jsonRequest(issuer + "/mcp/oauth/register", { client_name: "Paperclip CLI (device)", redirect_uris: [], grant_types: [deviceGrant, "refresh_token"], response_types: [], token_endpoint_auth_method: "none" });
if (!registration.ok || typeof registration.data.client_id !== "string") throw new Error("Could not register the Paperclip device client.");
const clientId = registration.data.client_id;
const authorization = await jsonRequest(issuer + "/mcp/oauth/device_authorization", { client_id: clientId, resource, scope: PUBLIC_MCP_SCOPES.join(" "), ...(companyId ? { company_id: companyId } : {}) });
const device = authorization.data;
if (!authorization.ok || typeof device.device_code !== "string" || typeof device.user_code !== "string"
|| device.verification_uri !== issuer + "/mcp-device" || typeof device.expires_in !== "number") throw new Error("Could not start device authorization.");
const verification = new URL(device.verification_uri); verification.searchParams.set("user_code", device.user_code);
notify(`Approve Paperclip access in your browser: ${verification}\nConfirm code: ${device.user_code}\nWaiting for your approval…`);
let interval = typeof device.interval === "number" ? Math.max(5, device.interval) : 5;
const deadline = Date.now() + Math.min(600, device.expires_in) * 1000;
while (Date.now() < deadline) {
await sleep(interval * 1000);
const result = await jsonRequest(issuer + "/mcp/oauth/token", { grant_type: deviceGrant, client_id: clientId, resource, device_code: device.device_code });
if (!result.ok) {
if (result.data.error === "authorization_pending") continue;
if (result.data.error === "slow_down") { interval += 5; continue; }
throw new Error(result.data.error === "access_denied" ? "Connection declined. No access was granted." : "Device authorization expired or failed. Start login again.");
}
const credential = tokens(result.data, { resource, issuer, clientId, companyId: companyId ?? "" });
const identity = await mcpRpc(resource, credential.accessToken, "tools/call", { name: "paperclip_connection", arguments: {} });
const connected = identity.structuredContent as Json | undefined;
if (identity.isError || typeof connected?.companyId !== "string" || (companyId && connected.companyId !== companyId)) throw new Error("The approved organization did not match. Reconnect before doing work.");
credential.companyId = connected.companyId;
const file = credentialPath(resource);
await replaceMcpCredential(file, credential, notify);
return { resource, companyId: credential.companyId };
}
throw new Error("Device authorization expired. Start login again.");
}
export async function replaceMcpCredential(file: string, credential: McpCredential, notify: (message: string) => void) {
await withMcpCredentialLock(file, async () => {
const previous = await readCredential(file);
// Persist the working replacement before changing authority on the server.
await saveCredential(file, credential);
if (previous && previous.resource === credential.resource && previous.issuer === credential.issuer) {
try { await revoke(previous); }
catch { notify("Connected. The previous connection could not be revoked; revoke it in Paperclip Connections."); }
}
});
}
export async function mcpAccessToken(raw: string) {
const resource = mcpResource(raw);
const file = credentialPath(resource);
return withMcpCredentialLock(file, async () => {
const credential = await readCredential(file);
if (!credential || credential.resource !== resource || credential.issuer !== new URL(resource).origin) throw new Error("Connect first with paperclipai mcp login --device --url <MCP URL>.");
if (credential.expiresAt > Date.now() + 30_000) return credential.accessToken;
if (!credential.refreshToken) throw new Error("Paperclip access expired. Sign in again.");
// Validate issuer discovery again before sending a stored credential.
await discovery(resource);
const result = await jsonRequest(credential.issuer + "/mcp/oauth/token", { grant_type: "refresh_token", client_id: credential.clientId, resource, refresh_token: credential.refreshToken });
if (!result.ok) throw new Error("Paperclip access was revoked or expired. Sign in again.");
const updated = tokens(result.data, credential);
await saveCredential(file, updated);
return updated.accessToken;
});
}