@alfe.ai/mcp-tools 0.1.0

package/dist/index.cjs

@@ -0,0 +1,80 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/types.ts
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data, null, 2)
+	}] };
+}
+function err(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+//#endregion
+//#region src/integrations.ts
+const OAUTH_PROVIDERS = [
+	"xero",
+	"google",
+	"notion",
+	"microsoft",
+	"atlassian",
+	"myob",
+	"github",
+	"discord",
+	"slack"
+];
+/**
+* Thin-slice subset of the `services/mcp` `integrations` domain — only
+* the two subtools whose underlying calls already hit public
+* `/agent/...` (or unauthenticated public) endpoints today. The rest of
+* the domain stays in `services/mcp` until the per-domain endpoint
+* promotion workstream lifts it (see
+* `project_mcp_tool_lift_workstream.md`).
+*
+* - `integrations_browse_registry` — public `GET /integrations/registry`
+*   via `AgentApiClient.getRegistry()`.
+* - `integrations_start_oauth` — generates the public
+*   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+*   Pure URL builder; no server-side call.
+*/
+const registerIntegrationsTools = (server, ctx) => {
+	server.registerTool("integrations_browse_registry", {
+		description: "Browse available integrations in the registry. Returns the catalogue of all published integrations with their manifests.",
+		inputSchema: {}
+	}, async () => {
+		try {
+			return ok(await ctx.client.getRegistry());
+		} catch (error) {
+			return err(error instanceof Error ? error.message : "Failed to browse integrations");
+		}
+	});
+	server.registerTool("integrations_start_oauth", {
+		description: "Start an OAuth connection flow for an integration. Returns a URL the user must open in their browser to authorize the connection. After authorization, use `integrations_check_oauth_status` (currently in services/mcp) to verify.",
+		inputSchema: {
+			provider: zod.z.enum(OAUTH_PROVIDERS).describe("The OAuth provider to connect"),
+			scopes: zod.z.string().optional().describe("Comma-separated scope groups (e.g. 'gmail,drive' for Google)")
+		}
+	}, ({ provider, scopes }) => {
+		const params = new URLSearchParams({
+			agentId: ctx.agentId,
+			tenantId: ctx.tenantId
+		});
+		if (scopes) params.set("scopes", scopes);
+		const url = `${ctx.apiUrl}/${provider}/oauth/start?${params.toString()}`;
+		return Promise.resolve(ok({
+			url,
+			provider,
+			message: `Open this URL to connect ${provider}: ${url}`
+		}));
+	});
+};
+//#endregion
+exports.err = err;
+exports.ok = ok;
+exports.registerIntegrationsTools = registerIntegrationsTools;

package/dist/index.d.cts

@@ -0,0 +1,75 @@
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/types.d.ts
+
+/**
+ * Context every tool registration function receives. The same context is
+ * used by the CLI-bundled local server (`@alfe.ai/mcp-server`) and the
+ * eventual lift target for `services/mcp` once each domain's public
+ * `/agent/...` endpoints land.
+ *
+ * `agentId` / `tenantId` are derived from `client.whoami()` at the local
+ * server's startup. They're carried in the context so tools that need
+ * them (e.g. OAuth-URL builders) don't have to re-issue a whoami call
+ * per invocation.
+ */
+interface ToolContext {
+  client: AgentApiClient;
+  apiUrl: string;
+  agentId: string;
+  tenantId: string;
+}
+/**
+ * Tool registration function shape. Each domain module exports one of
+ * these; the server calls them with the live `McpServer` and a
+ * `ToolContext`. Implementations call `server.registerTool(name, …)` for
+ * each subtool they own.
+ *
+ * Tool names follow the `<domain>_<verb>` convention (no `alfe_` prefix —
+ * the bundler namespaces the surface as `mcp__alfe-platform__<name>`).
+ */
+type RegisterToolsFn = (server: McpServer, ctx: ToolContext) => void;
+/**
+ * Standard error-result envelope mirroring the existing `services/mcp`
+ * shape so the lifted tool surface stays drop-in compatible for any
+ * downstream MCP client.
+ *
+ * The index signature satisfies the MCP SDK's `CallToolResult` shape —
+ * the SDK declares its result type with `[x: string]: unknown` so
+ * callers can add transport-level metadata. We don't use any, but the
+ * shape needs to be assignable for the registration callback to typecheck.
+ */
+interface ToolResult {
+  content: {
+    type: 'text';
+    text: string;
+  }[];
+  isError?: boolean;
+  [key: string]: unknown;
+}
+declare function ok(data: unknown): ToolResult;
+declare function err(message: string): ToolResult;
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/integrations.d.ts
+/**
+ * Thin-slice subset of the `services/mcp` `integrations` domain — only
+ * the two subtools whose underlying calls already hit public
+ * `/agent/...` (or unauthenticated public) endpoints today. The rest of
+ * the domain stays in `services/mcp` until the per-domain endpoint
+ * promotion workstream lifts it (see
+ * `project_mcp_tool_lift_workstream.md`).
+ *
+ * - `integrations_browse_registry` — public `GET /integrations/registry`
+ *   via `AgentApiClient.getRegistry()`.
+ * - `integrations_start_oauth` — generates the public
+ *   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+ *   Pure URL builder; no server-side call.
+ */
+declare const registerIntegrationsTools: RegisterToolsFn;
+//# sourceMappingURL=integrations.d.ts.map
+
+//#endregion
+export { type RegisterToolsFn, type ToolContext, type ToolResult, err, ok, registerIntegrationsTools };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/integrations.ts"],"mappings":";;;;;;;AAcA;AAgBA;;;;;AAYA;AAMA;AAMA;UAxCiB,WAAA;UACP;;ECcG,OAAA,EAAA,MAAA;;;;;;;;;;;;KDCD,eAAA,YAA2B,gBAAgB;;;;;;;;;;;UAYtC,UAAA;;;;;;;;iBAMD,EAAA,iBAAmB;iBAMnB,GAAA,mBAAsB;;;;;;;AAxCtC;AAgBA;;;;;AAYA;AAMA;AAMA;;;cCzBa,2BAA2B;AAAxC"}

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/types.d.ts
+
+/**
+ * Context every tool registration function receives. The same context is
+ * used by the CLI-bundled local server (`@alfe.ai/mcp-server`) and the
+ * eventual lift target for `services/mcp` once each domain's public
+ * `/agent/...` endpoints land.
+ *
+ * `agentId` / `tenantId` are derived from `client.whoami()` at the local
+ * server's startup. They're carried in the context so tools that need
+ * them (e.g. OAuth-URL builders) don't have to re-issue a whoami call
+ * per invocation.
+ */
+interface ToolContext {
+  client: AgentApiClient;
+  apiUrl: string;
+  agentId: string;
+  tenantId: string;
+}
+/**
+ * Tool registration function shape. Each domain module exports one of
+ * these; the server calls them with the live `McpServer` and a
+ * `ToolContext`. Implementations call `server.registerTool(name, …)` for
+ * each subtool they own.
+ *
+ * Tool names follow the `<domain>_<verb>` convention (no `alfe_` prefix —
+ * the bundler namespaces the surface as `mcp__alfe-platform__<name>`).
+ */
+type RegisterToolsFn = (server: McpServer, ctx: ToolContext) => void;
+/**
+ * Standard error-result envelope mirroring the existing `services/mcp`
+ * shape so the lifted tool surface stays drop-in compatible for any
+ * downstream MCP client.
+ *
+ * The index signature satisfies the MCP SDK's `CallToolResult` shape —
+ * the SDK declares its result type with `[x: string]: unknown` so
+ * callers can add transport-level metadata. We don't use any, but the
+ * shape needs to be assignable for the registration callback to typecheck.
+ */
+interface ToolResult {
+  content: {
+    type: 'text';
+    text: string;
+  }[];
+  isError?: boolean;
+  [key: string]: unknown;
+}
+declare function ok(data: unknown): ToolResult;
+declare function err(message: string): ToolResult;
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/integrations.d.ts
+/**
+ * Thin-slice subset of the `services/mcp` `integrations` domain — only
+ * the two subtools whose underlying calls already hit public
+ * `/agent/...` (or unauthenticated public) endpoints today. The rest of
+ * the domain stays in `services/mcp` until the per-domain endpoint
+ * promotion workstream lifts it (see
+ * `project_mcp_tool_lift_workstream.md`).
+ *
+ * - `integrations_browse_registry` — public `GET /integrations/registry`
+ *   via `AgentApiClient.getRegistry()`.
+ * - `integrations_start_oauth` — generates the public
+ *   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+ *   Pure URL builder; no server-side call.
+ */
+declare const registerIntegrationsTools: RegisterToolsFn;
+//# sourceMappingURL=integrations.d.ts.map
+
+//#endregion
+export { type RegisterToolsFn, type ToolContext, type ToolResult, err, ok, registerIntegrationsTools };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/integrations.ts"],"mappings":";;;;;;;AAcA;AAgBA;;;;;AAYA;AAMA;AAMA;UAxCiB,WAAA;UACP;;ECcG,OAAA,EAAA,MAAA;;;;;;;;;;;;KDCD,eAAA,YAA2B,gBAAgB;;;;;;;;;;;UAYtC,UAAA;;;;;;;;iBAMD,EAAA,iBAAmB;iBAMnB,GAAA,mBAAsB;;;;;;;AAxCtC;AAgBA;;;;;AAYA;AAMA;AAMA;;;cCzBa,2BAA2B;AAAxC"}

package/dist/index.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+//#region src/types.ts
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data, null, 2)
+	}] };
+}
+function err(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+//#endregion
+//#region src/integrations.ts
+const OAUTH_PROVIDERS = [
+	"xero",
+	"google",
+	"notion",
+	"microsoft",
+	"atlassian",
+	"myob",
+	"github",
+	"discord",
+	"slack"
+];
+/**
+* Thin-slice subset of the `services/mcp` `integrations` domain — only
+* the two subtools whose underlying calls already hit public
+* `/agent/...` (or unauthenticated public) endpoints today. The rest of
+* the domain stays in `services/mcp` until the per-domain endpoint
+* promotion workstream lifts it (see
+* `project_mcp_tool_lift_workstream.md`).
+*
+* - `integrations_browse_registry` — public `GET /integrations/registry`
+*   via `AgentApiClient.getRegistry()`.
+* - `integrations_start_oauth` — generates the public
+*   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+*   Pure URL builder; no server-side call.
+*/
+const registerIntegrationsTools = (server, ctx) => {
+	server.registerTool("integrations_browse_registry", {
+		description: "Browse available integrations in the registry. Returns the catalogue of all published integrations with their manifests.",
+		inputSchema: {}
+	}, async () => {
+		try {
+			return ok(await ctx.client.getRegistry());
+		} catch (error) {
+			return err(error instanceof Error ? error.message : "Failed to browse integrations");
+		}
+	});
+	server.registerTool("integrations_start_oauth", {
+		description: "Start an OAuth connection flow for an integration. Returns a URL the user must open in their browser to authorize the connection. After authorization, use `integrations_check_oauth_status` (currently in services/mcp) to verify.",
+		inputSchema: {
+			provider: z.enum(OAUTH_PROVIDERS).describe("The OAuth provider to connect"),
+			scopes: z.string().optional().describe("Comma-separated scope groups (e.g. 'gmail,drive' for Google)")
+		}
+	}, ({ provider, scopes }) => {
+		const params = new URLSearchParams({
+			agentId: ctx.agentId,
+			tenantId: ctx.tenantId
+		});
+		if (scopes) params.set("scopes", scopes);
+		const url = `${ctx.apiUrl}/${provider}/oauth/start?${params.toString()}`;
+		return Promise.resolve(ok({
+			url,
+			provider,
+			message: `Open this URL to connect ${provider}: ${url}`
+		}));
+	});
+};
+//#endregion
+export { err, ok, registerIntegrationsTools };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/types.ts","../src/integrations.ts"],"sourcesContent":["import type { AgentApiClient } from '@alfe.ai/agent-api-client';\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\n/**\n * Context every tool registration function receives. The same context is\n * used by the CLI-bundled local server (`@alfe.ai/mcp-server`) and the\n * eventual lift target for `services/mcp` once each domain's public\n * `/agent/...` endpoints land.\n *\n * `agentId` / `tenantId` are derived from `client.whoami()` at the local\n * server's startup. They're carried in the context so tools that need\n * them (e.g. OAuth-URL builders) don't have to re-issue a whoami call\n * per invocation.\n */\nexport interface ToolContext {\n  client: AgentApiClient;\n  apiUrl: string;\n  agentId: string;\n  tenantId: string;\n}\n\n/**\n * Tool registration function shape. Each domain module exports one of\n * these; the server calls them with the live `McpServer` and a\n * `ToolContext`. Implementations call `server.registerTool(name, …)` for\n * each subtool they own.\n *\n * Tool names follow the `<domain>_<verb>` convention (no `alfe_` prefix —\n * the bundler namespaces the surface as `mcp__alfe-platform__<name>`).\n */\nexport type RegisterToolsFn = (server: McpServer, ctx: ToolContext) => void;\n\n/**\n * Standard error-result envelope mirroring the existing `services/mcp`\n * shape so the lifted tool surface stays drop-in compatible for any\n * downstream MCP client.\n *\n * The index signature satisfies the MCP SDK's `CallToolResult` shape —\n * the SDK declares its result type with `[x: string]: unknown` so\n * callers can add transport-level metadata. We don't use any, but the\n * shape needs to be assignable for the registration callback to typecheck.\n */\nexport interface ToolResult {\n  content: { type: 'text'; text: string }[];\n  isError?: boolean;\n  [key: string]: unknown;\n}\n\nexport function ok(data: unknown): ToolResult {\n  return {\n    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],\n  };\n}\n\nexport function err(message: string): ToolResult {\n  return {\n    content: [{ type: 'text', text: message }],\n    isError: true,\n  };\n}\n","import { z } from 'zod';\nimport { err, ok, type RegisterToolsFn, type ToolContext } from './types.js';\n\nconst OAUTH_PROVIDERS = [\n  'xero',\n  'google',\n  'notion',\n  'microsoft',\n  'atlassian',\n  'myob',\n  'github',\n  'discord',\n  'slack',\n] as const;\n\n/**\n * Thin-slice subset of the `services/mcp` `integrations` domain — only\n * the two subtools whose underlying calls already hit public\n * `/agent/...` (or unauthenticated public) endpoints today. The rest of\n * the domain stays in `services/mcp` until the per-domain endpoint\n * promotion workstream lifts it (see\n * `project_mcp_tool_lift_workstream.md`).\n *\n * - `integrations_browse_registry` — public `GET /integrations/registry`\n *   via `AgentApiClient.getRegistry()`.\n * - `integrations_start_oauth` — generates the public\n *   `GET /<provider>/oauth/start` URL for the user to open in a browser.\n *   Pure URL builder; no server-side call.\n */\nexport const registerIntegrationsTools: RegisterToolsFn = (server, ctx: ToolContext): void => {\n  server.registerTool(\n    'integrations_browse_registry',\n    {\n      description:\n        'Browse available integrations in the registry. Returns the catalogue of all published integrations with their manifests.',\n      inputSchema: {},\n    },\n    async () => {\n      try {\n        const data = await ctx.client.getRegistry();\n        return ok(data);\n      } catch (error: unknown) {\n        return err(error instanceof Error ? error.message : 'Failed to browse integrations');\n      }\n    },\n  );\n\n  server.registerTool(\n    'integrations_start_oauth',\n    {\n      description:\n        'Start an OAuth connection flow for an integration. Returns a URL the user must open in their browser to authorize the connection. After authorization, use `integrations_check_oauth_status` (currently in services/mcp) to verify.',\n      inputSchema: {\n        provider: z\n          .enum(OAUTH_PROVIDERS)\n          .describe('The OAuth provider to connect'),\n        scopes: z\n          .string()\n          .optional()\n          .describe(\"Comma-separated scope groups (e.g. 'gmail,drive' for Google)\"),\n      },\n    },\n    ({ provider, scopes }: { provider: (typeof OAUTH_PROVIDERS)[number]; scopes?: string }) => {\n      const params = new URLSearchParams({ agentId: ctx.agentId, tenantId: ctx.tenantId });\n      if (scopes) params.set('scopes', scopes);\n      const url = `${ctx.apiUrl}/${provider}/oauth/start?${params.toString()}`;\n      return Promise.resolve(\n        ok({\n          url,\n          provider,\n          message: `Open this URL to connect ${provider}: ${url}`,\n        }),\n      );\n    },\n  );\n};\n"],"mappings":";;AAgDA,SAAgB,GAAG,MAA2B;AAC5C,QAAO,EACL,SAAS,CAAC;EAAE,MAAM;EAAQ,MAAM,KAAK,UAAU,MAAM,MAAM,EAAE;EAAE,CAAC,EACjE;;AAGH,SAAgB,IAAI,SAA6B;AAC/C,QAAO;EACL,SAAS,CAAC;GAAE,MAAM;GAAQ,MAAM;GAAS,CAAC;EAC1C,SAAS;EACV;;;;ACvDH,MAAM,kBAAkB;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;AAgBD,MAAa,6BAA8C,QAAQ,QAA2B;AAC5F,QAAO,aACL,gCACA;EACE,aACE;EACF,aAAa,EAAE;EAChB,EACD,YAAY;AACV,MAAI;AAEF,UAAO,GADM,MAAM,IAAI,OAAO,aAAa,CAC5B;WACR,OAAgB;AACvB,UAAO,IAAI,iBAAiB,QAAQ,MAAM,UAAU,gCAAgC;;GAGzF;AAED,QAAO,aACL,4BACA;EACE,aACE;EACF,aAAa;GACX,UAAU,EACP,KAAK,gBAAgB,CACrB,SAAS,gCAAgC;GAC5C,QAAQ,EACL,QAAQ,CACR,UAAU,CACV,SAAS,+DAA+D;GAC5E;EACF,GACA,EAAE,UAAU,aAA8E;EACzF,MAAM,SAAS,IAAI,gBAAgB;GAAE,SAAS,IAAI;GAAS,UAAU,IAAI;GAAU,CAAC;AACpF,MAAI,OAAQ,QAAO,IAAI,UAAU,OAAO;EACxC,MAAM,MAAM,GAAG,IAAI,OAAO,GAAG,SAAS,eAAe,OAAO,UAAU;AACtE,SAAO,QAAQ,QACb,GAAG;GACD;GACA;GACA,SAAS,4BAA4B,SAAS,IAAI;GACnD,CAAC,CACH;GAEJ"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@alfe.ai/mcp-tools",
+  "version": "0.1.0",
+  "description": "Shared MCP tool implementations for Alfe's local CLI-bundled MCP server and (later) the Fly-deployed services/mcp. All tools use AgentApiClient against public /agent/... endpoints — never InternalClient.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0",
+    "@alfe.ai/agent-api-client": "0.1.4"
+  },
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}