@gemstack/connectors 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @gemstack/connectors
+
+The connector contract for GemStack AI orchestration. Define a tool connector to an external service (GitHub, Google Drive, ...) once with `defineConnector`, then compose any number of connectors into a single MCP server with `mountConnectors`.
+
+Built on [`@gemstack/mcp`](../mcp). Framework-agnostic: the server it produces plugs into the same surface as any other `@gemstack/mcp` server (`Mcp.web` / `Mcp.local`, `McpTestClient`, the neutral HTTP handler).
+
+> A connector only **declares** what it needs (its auth requirement) and **what it does** (its tools). It never reaches for env vars, OAuth, or a transport itself. The orchestrator that mounts it supplies credentials and chooses how to serve it. That split is what lets first-party and third-party connectors compose interchangeably.
+
+## Install
+
+```bash
+npm i @gemstack/connectors @gemstack/mcp zod
+```
+
+## Define a connector
+
+```ts
+import { defineConnector } from '@gemstack/connectors'
+import { z } from 'zod'
+
+export default defineConnector({
+  id: 'notes', // lowercase, used to namespace this connector's tools
+  name: 'Notes',
+  auth: { type: 'none' }, // 'none' | 'pat' | 'oauth'
+  tools: [
+    {
+      name: 'list',
+      description: 'List all notes',
+      schema: z.object({}),
+      annotations: { readOnly: true },
+      handle: () => ['buy milk', 'ship connectors'],
+    },
+    {
+      name: 'get',
+      description: 'Get one note by index',
+      schema: z.object({ index: z.number() }),
+      annotations: { readOnly: true },
+      handle: (input, ctx) => {
+        // ctx.auth carries the credential the orchestrator resolved for 'notes'
+        return getNote(input.index)
+      },
+    },
+  ],
+})
+```
+
+A tool's `handle` may return a `string` (wrapped as text), any JSON-serializable value (wrapped as pretty JSON), or a full `McpToolResult` (use `McpResponse` from `@gemstack/mcp` for errors / images).
+
+## Mount connectors into a server
+
+```ts
+import { mountConnectors } from '@gemstack/connectors'
+import { Mcp } from '@gemstack/mcp'
+import notes from './notes.js'
+import github from '@gemstack/connector-github'
+
+const Server = mountConnectors([notes, github], {
+  name: 'my-orchestrator',
+  // Resolve each connector's credential at call time. This is the seam that
+  // satisfies a connector's declared `auth`.
+  credentials: (id) => ({ token: process.env[`${id.toUpperCase()}_TOKEN`] }),
+})
+
+// The result is a standard @gemstack/mcp server class.
+Mcp.web('/mcp/connectors', Server)
+```
+
+Tools are namespaced by connector id, so `notes.list` is exposed as `notes_list` and never collides with another connector's `list`. Pass `namespace: 'none'` to keep names verbatim (you then own collision-avoidance).
+
+## Auth requirements
+
+A connector declares one of:
+
+| `auth.type` | Means | Credential the orchestrator provides |
+|---|---|---|
+| `none` | Public / local data | `{}` |
+| `pat` | Personal access token / API key (`env` names a default var) | `{ token }` |
+| `oauth` | OAuth 2.1 bearer (`scopes`, `authorizationServers`) | `{ token }` |
+
+For `oauth`, protect the mounted endpoint with `@gemstack/mcp`'s `oauth2McpMiddleware` + `registerOAuth2Metadata` and feed the verified token through `credentials`.
+
+## Testing
+
+```ts
+import { McpTestClient } from '@gemstack/mcp/testing'
+import { mountConnectors } from '@gemstack/connectors'
+
+const client = new McpTestClient(mountConnectors([notes]))
+await client.listTools() // [{ name: 'notes_list', ... }, { name: 'notes_get', ... }]
+await client.callTool('notes_get', { index: 0 })
+```
+
+## API
+
+- `defineConnector(def): Connector` — validate + fill defaults.
+- `mountConnectors(connectors, options?): ConnectorServerClass` — compose into one `@gemstack/mcp` server class.
+
+See `examples/connectors-quickstart` in the repo for a runnable reference connector to copy from.

package/dist/defineConnector.d.ts

@@ -0,0 +1,15 @@
+import type { Connector, ConnectorDefinition } from './types.js';
+/**
+ * Define a tool connector to an external service. Validates the shape and fills
+ * defaults, returning a {@link Connector} ready to pass to `mountConnectors`.
+ *
+ * ```ts
+ * export default defineConnector({
+ *   id: 'github',
+ *   auth: { type: 'oauth', scopes: ['repo'] },
+ *   tools: [{ name: 'list-issues', schema: ..., handle: async (input, ctx) => ... }],
+ * })
+ * ```
+ */
+export declare function defineConnector(def: ConnectorDefinition): Connector;
+//# sourceMappingURL=defineConnector.d.ts.map

package/dist/defineConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineConnector.d.ts","sourceRoot":"","sources":["../src/defineConnector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAKhE;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,CAwCnE"}

package/dist/defineConnector.js

@@ -0,0 +1,50 @@
+/** Connector ids and tool names share this charset so namespaced names stay MCP-safe. */
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Define a tool connector to an external service. Validates the shape and fills
+ * defaults, returning a {@link Connector} ready to pass to `mountConnectors`.
+ *
+ * ```ts
+ * export default defineConnector({
+ *   id: 'github',
+ *   auth: { type: 'oauth', scopes: ['repo'] },
+ *   tools: [{ name: 'list-issues', schema: ..., handle: async (input, ctx) => ... }],
+ * })
+ * ```
+ */
+export function defineConnector(def) {
+    if (!def || typeof def !== 'object') {
+        throw new TypeError('defineConnector: expected a connector definition object');
+    }
+    if (!ID_RE.test(def.id ?? '')) {
+        throw new Error(`defineConnector: invalid id ${JSON.stringify(def.id)} — use lowercase letters, digits, and "-" (must start with a letter)`);
+    }
+    if (!Array.isArray(def.tools) || def.tools.length === 0) {
+        throw new Error(`defineConnector("${def.id}"): at least one tool is required`);
+    }
+    const seen = new Set();
+    for (const tool of def.tools) {
+        if (!ID_RE.test(tool?.name ?? '')) {
+            throw new Error(`defineConnector("${def.id}"): invalid tool name ${JSON.stringify(tool?.name)} — use lowercase letters, digits, and "-"`);
+        }
+        if (seen.has(tool.name)) {
+            throw new Error(`defineConnector("${def.id}"): duplicate tool name "${tool.name}"`);
+        }
+        seen.add(tool.name);
+        if (typeof tool.handle !== 'function') {
+            throw new Error(`defineConnector("${def.id}"): tool "${tool.name}" is missing a handle() function`);
+        }
+        if (typeof tool.schema !== 'object' || tool.schema == null) {
+            throw new Error(`defineConnector("${def.id}"): tool "${tool.name}" is missing a Zod schema`);
+        }
+    }
+    return {
+        id: def.id,
+        name: def.name ?? def.id,
+        version: def.version ?? '1.0.0',
+        ...(def.instructions != null ? { instructions: def.instructions } : {}),
+        auth: def.auth ?? { type: 'none' },
+        tools: def.tools,
+    };
+}
+//# sourceMappingURL=defineConnector.js.map

package/dist/defineConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineConnector.js","sourceRoot":"","sources":["../src/defineConnector.ts"],"names":[],"mappings":"AAEA,yFAAyF;AACzF,MAAM,KAAK,GAAG,mBAAmB,CAAA;AAEjC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,GAAwB;IACtD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAA;IAChF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,+BAA+B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,sEAAsE,CAC5H,CAAA;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC,EAAE,mCAAmC,CAAC,CAAA;IAChF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,oBAAoB,GAAG,CAAC,EAAE,yBAAyB,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,2CAA2C,CACzH,CAAA;QACH,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC,EAAE,4BAA4B,IAAI,CAAC,IAAI,GAAG,CAAC,CAAA;QACrF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnB,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC,EAAE,aAAa,IAAI,CAAC,IAAI,kCAAkC,CAAC,CAAA;QACrG,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC,EAAE,aAAa,IAAI,CAAC,IAAI,2BAA2B,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE;QACxB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,OAAO;QAC/B,GAAG,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;QAClC,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { defineConnector } from './defineConnector.js';
+export { mountConnectors } from './mountConnectors.js';
+export type { ConnectorServerClass, MountOptions } from './mountConnectors.js';
+export type { Connector, ConnectorDefinition, ConnectorTool, ConnectorToolAnnotations, ConnectorToolReturn, ConnectorAuth, ConnectorContext, Credential, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAC9E,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { defineConnector } from './defineConnector.js';
+export { mountConnectors } from './mountConnectors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/mountConnectors.d.ts

@@ -0,0 +1,42 @@
+import { McpServer } from '@gemstack/mcp';
+import type { McpServerOptions } from '@gemstack/mcp';
+import type { Connector, Credential } from './types.js';
+/** A constructable MCP server, ready for `Mcp.web()` / `Mcp.local()` or `McpTestClient`. */
+export type ConnectorServerClass = new (options?: McpServerOptions) => McpServer;
+export interface MountOptions {
+    /** Server name advertised to clients. Default `"connectors"`. */
+    name?: string;
+    /** Server version. Default `"1.0.0"`. */
+    version?: string;
+    /** Server-level instructions surfaced to the agent. */
+    instructions?: string;
+    /**
+     * Resolve the credential for a connector at tool-call time. Called with the
+     * connector id before each tool runs; return `undefined` for connectors that
+     * need none. This is the seam the orchestrator implements to satisfy each
+     * connector's declared {@link Connector.auth}.
+     */
+    credentials?: (connectorId: string) => Credential | undefined | Promise<Credential | undefined>;
+    /**
+     * How tool names are disambiguated across connectors.
+     * - `'prefix'` (default): `"<connectorId>_<toolName>"`.
+     * - `'none'`: tool names kept verbatim (you must ensure they don't collide).
+     */
+    namespace?: 'prefix' | 'none';
+}
+/**
+ * Compose any number of connectors into a single MCP server class. Each
+ * connector's tools become MCP tools on one server, namespaced by connector id
+ * so names never collide. The returned class plugs straight into the
+ * @gemstack/mcp surface: register it with `Mcp.web(path, ServerClass)` /
+ * `Mcp.local(name, ServerClass)`, or drive it in tests with `McpTestClient`.
+ *
+ * ```ts
+ * const Server = mountConnectors([github, drive], {
+ *   credentials: (id) => ({ token: process.env[`${id.toUpperCase()}_TOKEN`] }),
+ * })
+ * Mcp.web('/mcp/connectors', Server)
+ * ```
+ */
+export declare function mountConnectors(connectors: Connector[], options?: MountOptions): ConnectorServerClass;
+//# sourceMappingURL=mountConnectors.d.ts.map

package/dist/mountConnectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountConnectors.d.ts","sourceRoot":"","sources":["../src/mountConnectors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAOV,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,gBAAgB,EAAgC,MAAM,eAAe,CAAA;AACnF,OAAO,KAAK,EAAE,SAAS,EAAwD,UAAU,EAAE,MAAM,YAAY,CAAA;AAE7G,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,KAAK,OAAO,CAAC,EAAE,gBAAgB,KAAK,SAAS,CAAA;AAEhF,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;IAC/F;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,oBAAoB,CA4BzG"}

package/dist/mountConnectors.js

@@ -0,0 +1,83 @@
+import { McpServer, McpTool, McpResponse, IsReadOnly, IsDestructive, IsIdempotent, IsOpenWorld, } from '@gemstack/mcp';
+/**
+ * Compose any number of connectors into a single MCP server class. Each
+ * connector's tools become MCP tools on one server, namespaced by connector id
+ * so names never collide. The returned class plugs straight into the
+ * @gemstack/mcp surface: register it with `Mcp.web(path, ServerClass)` /
+ * `Mcp.local(name, ServerClass)`, or drive it in tests with `McpTestClient`.
+ *
+ * ```ts
+ * const Server = mountConnectors([github, drive], {
+ *   credentials: (id) => ({ token: process.env[`${id.toUpperCase()}_TOKEN`] }),
+ * })
+ * Mcp.web('/mcp/connectors', Server)
+ * ```
+ */
+export function mountConnectors(connectors, options = {}) {
+    const namespace = options.namespace ?? 'prefix';
+    const toolClasses = [];
+    const seen = new Set();
+    for (const connector of connectors) {
+        for (const tool of connector.tools) {
+            const toolName = namespace === 'prefix' ? `${connector.id}_${tool.name}` : tool.name;
+            if (seen.has(toolName)) {
+                throw new Error(`mountConnectors: duplicate tool name "${toolName}" — two connectors expose the same tool (use namespace: 'prefix')`);
+            }
+            seen.add(toolName);
+            toolClasses.push(makeToolClass(connector, tool, toolName, options));
+        }
+    }
+    const name = options.name ?? 'connectors';
+    const version = options.version ?? '1.0.0';
+    const instructions = options.instructions;
+    return class ConnectorsServer extends McpServer {
+        tools = toolClasses;
+        metadata() {
+            return { name, version, ...(instructions != null ? { instructions } : {}) };
+        }
+    };
+}
+function makeToolClass(connector, tool, toolName, options) {
+    class ConnectorToolImpl extends McpTool {
+        name() {
+            return toolName;
+        }
+        description() {
+            return tool.description ?? '';
+        }
+        schema() {
+            return tool.schema;
+        }
+        async handle(input) {
+            const auth = (await options.credentials?.(connector.id)) ?? {};
+            const ctx = { connectorId: connector.id, auth };
+            return normalizeResult(await tool.handle(input, ctx));
+        }
+    }
+    if (tool.outputSchema) {
+        const outputSchema = tool.outputSchema;
+        ConnectorToolImpl.prototype.outputSchema = () => outputSchema;
+    }
+    const a = tool.annotations;
+    if (a?.readOnly)
+        IsReadOnly(true)(ConnectorToolImpl);
+    if (a?.destructive)
+        IsDestructive(true)(ConnectorToolImpl);
+    if (a?.idempotent)
+        IsIdempotent(true)(ConnectorToolImpl);
+    if (a?.openWorld)
+        IsOpenWorld(true)(ConnectorToolImpl);
+    return ConnectorToolImpl;
+}
+/** Wrap a connector handler's return into a {@link McpToolResult}. */
+function normalizeResult(result) {
+    if (isToolResult(result))
+        return result;
+    if (typeof result === 'string')
+        return McpResponse.text(result);
+    return McpResponse.json(result);
+}
+function isToolResult(value) {
+    return !!value && typeof value === 'object' && Array.isArray(value.content);
+}
+//# sourceMappingURL=mountConnectors.js.map

package/dist/mountConnectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountConnectors.js","sourceRoot":"","sources":["../src/mountConnectors.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+import type { McpToolResult, ZodLikeObject } from '@gemstack/mcp';
+/**
+ * What credential a connector needs to reach its external service. The
+ * orchestrator reads this to know how to satisfy the connector, then hands a
+ * resolved {@link Credential} to each tool call. The connector only *declares*
+ * its requirement here; it never reaches for env vars or OAuth itself.
+ */
+export type ConnectorAuth = 
+/** No credential needed (public data, local source). */
+{
+    type: 'none';
+}
+/** A personal access token / API key. `env` names a default env var to read. */
+ | {
+    type: 'pat';
+    description?: string;
+    env?: string;
+}
+/** OAuth 2.1 bearer token. Mirrors the @gemstack/mcp OAuth protect options. */
+ | {
+    type: 'oauth';
+    scopes?: string[];
+    authorizationServers?: string[];
+    description?: string;
+};
+/**
+ * A credential resolved for one connector and handed to its tools at call time.
+ * `token` is the common case (PAT or bearer); extra fields carry anything else
+ * a connector's credential provider wants to thread through.
+ */
+export interface Credential {
+    token?: string | undefined;
+    [key: string]: unknown;
+}
+/** Context passed to every connector tool handler. */
+export interface ConnectorContext {
+    /** The id of the connector this tool belongs to. */
+    connectorId: string;
+    /** The credential resolved for this connector (`{}` when none was provided). */
+    auth: Credential;
+}
+/**
+ * What a tool handler may return:
+ * - a full {@link McpToolResult} (use `McpResponse` from @gemstack/mcp), or
+ * - a `string` (wrapped as a text result), or
+ * - any JSON-serializable value (wrapped as pretty-printed JSON text).
+ */
+export type ConnectorToolReturn = McpToolResult | string | unknown;
+/**
+ * Behavioural hints advertised to MCP clients. They mirror the MCP tool
+ * annotations and let agents reason about a tool before calling it — e.g. only
+ * auto-approve `readOnly` tools. Default (all unset) means a read-write,
+ * non-destructive, non-idempotent tool.
+ */
+export interface ConnectorToolAnnotations {
+    /** The tool does not modify any state. */
+    readOnly?: boolean;
+    /** The tool may perform destructive updates (deletes, overwrites). */
+    destructive?: boolean;
+    /** Calling repeatedly with the same input has no additional effect. */
+    idempotent?: boolean;
+    /** The tool interacts with the open world (external network / services). */
+    openWorld?: boolean;
+}
+/** A single tool a connector exposes. */
+export interface ConnectorTool<Input = Record<string, unknown>> {
+    /** Tool name, unique within the connector. Kept verbatim (namespaced at mount). */
+    name: string;
+    /** One-line description shown to the agent. */
+    description?: string;
+    /** Input schema — a Zod object (v3 or v4). */
+    schema: ZodLikeObject;
+    /** Optional output schema advertised to clients. */
+    outputSchema?: ZodLikeObject;
+    /** Optional behavioural hints. */
+    annotations?: ConnectorToolAnnotations;
+    /** Run the tool. Receives validated input and the connector {@link ConnectorContext}. */
+    handle: (input: Input, ctx: ConnectorContext) => ConnectorToolReturn | Promise<ConnectorToolReturn>;
+}
+/** The object passed to {@link defineConnector}. */
+export interface ConnectorDefinition {
+    /** Stable, unique id (lowercase letters, digits, `-`). Used to namespace tools. */
+    id: string;
+    /** Human-readable name. Defaults to `id`. */
+    name?: string;
+    /** Connector version. Defaults to `1.0.0`. */
+    version?: string;
+    /** Optional instructions surfaced to the agent at the server level. */
+    instructions?: string;
+    /** Credential requirement. Defaults to `{ type: 'none' }`. */
+    auth?: ConnectorAuth;
+    /**
+     * The tools this connector exposes (at least one). Typed loosely so each tool
+     * may annotate its own `handle` input (e.g. `(input: { id: string }) => ...`);
+     * the Zod `schema` is the runtime source of truth.
+     */
+    tools: ConnectorTool<any>[];
+}
+/** A validated connector, as returned by {@link defineConnector}. */
+export interface Connector {
+    id: string;
+    name: string;
+    version: string;
+    instructions?: string;
+    auth: ConnectorAuth;
+    tools: ConnectorTool<any>[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,aAAa;AACvB,wDAAwD;AACtD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,gFAAgF;GAC9E;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;AACrD,+EAA+E;GAC7E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/F;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAGzB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAElE;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAA;IACZ,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8CAA8C;IAC9C,MAAM,EAAE,aAAa,CAAA;IACrB,oDAAoD;IACpD,YAAY,CAAC,EAAE,aAAa,CAAA;IAC5B,kCAAkC;IAClC,WAAW,CAAC,EAAE,wBAAwB,CAAA;IACtC,yFAAyF;IACzF,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,gBAAgB,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;CACpG;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,EAAE,EAAE,MAAM,CAAA;IACV,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB;;;;OAIG;IAEH,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,aAAa,CAAA;IAEnB,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;CAC5B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@gemstack/connectors",
+  "version": "0.1.0",
+  "description": "The connector contract for GemStack AI orchestration: define a tool connector to an external service (GitHub, Google Drive, ...) once with `defineConnector`, compose any number into a single MCP server with `mountConnectors`. Built on @gemstack/mcp; framework-agnostic.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "connector",
+    "connectors",
+    "ai",
+    "agents",
+    "orchestration",
+    "tools",
+    "gemstack"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/gemstack-land/gemstack/tree/main/packages/connectors#readme",
+  "bugs": {
+    "url": "https://github.com/gemstack-land/gemstack/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gemstack-land/gemstack",
+    "directory": "packages/connectors"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.0",
+    "@gemstack/mcp": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "zod": "^4.0.0"
+  },
+  "author": "Suleiman Shahbari",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.test.json && cd dist-test && node --test",
+    "clean": "rm -rf dist dist-test"
+  }
+}