@drupalmcp/adk 0.1.0 → 0.2.0

package/README.md

@@ -37,9 +37,16 @@ unreachable. `drupalTools()` rewrites both on the way through. You can use
 the rewrite on its own with `normaliseSchema()`.
 
 **Explains a refusal.** A call the credential may not make comes back as
-HTTP 403 with a challenge naming the missing scope. The MCP client drops
-that header, so the library keeps it and gives the model a sentence that
-says what happened and that retrying will not help.
+HTTP 403 with a challenge naming the missing scope. That header is dropped
+before the error reaches you, so the library keeps it and gives the model a
+sentence that says what happened and that retrying will not help.
+
+**Resolves its dependencies once, at import.** The tools are built on the
+protocol SDK directly rather than on the agent kit's own MCP toolset, which
+looks the SDK up lazily at the first tool call from whatever directory it
+happens to be running in. That lookup fails inside the dev server's temporary
+build folder, reporting a missing dependency that is sitting in
+`node_modules`. Importing at the top of the file cannot fail that way.
 
 ## Agents defined in Drupal
 
@@ -65,13 +72,25 @@ is how a tone-of-voice rule reaches an agent running outside Drupal.
 long a definition is reused; it defaults to ten seconds and zero re-reads
 every turn.
 
+If the site has no such agent, the call refuses and says where to look rather
+than failing obscurely. Keep these agents in their own folder: the ADK dev
+server loads every agent in the directory you point it at, and one that cannot
+reach its definition will report that at startup.
+
 ## Choosing what the agent can reach
 
 ```ts
 drupalTools({ auth, only: ['tool_api__tool_belt_entity_list'] });
+drupalTools({ auth, except: ['tool_api__tool_belt_entity_bundle_list'] });
 ```
 
-`only` narrows the tool list. It is a convenience, not a boundary: what the
-agent may actually do is decided by the credential's scopes on the server.
+`only` narrows the tool list and `except` removes from it. Both are a
+convenience, not a boundary: what the agent may actually do is decided by the
+credential's scopes on the server.
+
+`except` earns its keep for a tool the site publishes that this credential can
+never run. Listing a content type's bundles, for instance, needs an
+administrator permission an agent should not have, so offering the tool only
+invites a refusal in the middle of a job.
 
 Apache-2.0. Part of [drupalmcp-ts](https://github.com/Omedia/drupalmcp-ts).

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { MCPToolset } from '@google/adk/tools/mcp';
-import { LlmAgent } from '@google/adk';
+import { BaseToolset, ReadonlyContext, BaseTool, LlmAgent } from '@google/adk';
 
 /**
  * OAuth 2 client credentials against a Drupal site running drupal/mcp.
@@ -59,6 +58,14 @@ declare class DrupalOAuth {
 
 /**
  * The Drupal site's MCP tools, ready to hand to an ADK agent.
+ *
+ * These are built on the protocol SDK directly rather than on the agent kit's
+ * own MCP toolset. The kit resolves the SDK lazily at the moment of the first
+ * tool call, from whatever directory it happens to be running in, and when its
+ * dev server transpiles an agent into a temporary folder that lookup can fail
+ * with a message claiming the SDK is not installed. Importing it here, at the
+ * top of the file, means it is resolved once when this module loads, and
+ * bundled with the agent by anything that bundles.
  */
 
 interface DrupalToolsOptions {
@@ -72,6 +79,12 @@ interface DrupalToolsOptions {
      * site publishes; the credential's scopes still decide what may run.
      */
     only?: string[];
+    /**
+     * Leave these tools out. Useful for a tool the site publishes but this
+     * credential can never run, such as one that needs an administrator
+     * permission: offering it only invites a refusal mid-conversation.
+     */
+    except?: string[];
     /** Prefix added to every tool name, for telling two sites apart. */
     prefix?: string;
 }
@@ -80,10 +93,41 @@ interface DrupalToolsOptions {
  *
  * The bearer token is attached per request rather than frozen into the
  * transport, so a token expiring mid-conversation is replaced without the
- * agent noticing. Tool schemas are rewritten on the way through; see
- * {@link normaliseSchema}.
+ * agent noticing.
  */
-declare function drupalTools(options: DrupalToolsOptions): MCPToolset;
+declare function drupalTools(options: DrupalToolsOptions): DrupalToolset;
+/**
+ * An ADK toolset backed by one MCP session against a Drupal site.
+ */
+declare class DrupalToolset extends BaseToolset {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly only;
+    private readonly except;
+    private readonly namePrefix;
+    /** The last authentication challenge the site sent, if any. */
+    private challenge;
+    private client;
+    private connecting;
+    constructor(options: DrupalToolsOptions);
+    /**
+     * {@inheritdoc}
+     */
+    getTools(_context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * {@inheritdoc}
+     */
+    close(): Promise<void>;
+    /**
+     * Runs one tool, translating a refusal into something the model can use.
+     *
+     * @internal
+     */
+    call(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** The connected client, opening the session on first use. */
+    private connect;
+    private open;
+}
 
 /**
  * Agents defined in Drupal, running in ADK.
@@ -203,6 +247,6 @@ declare function scopeFromChallenge(challenge: string | null | undefined): strin
 declare function describeRefusal(error: unknown): string | null;
 
 /** Kept in step with package.json; sent as the user agent. */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.0";
 
 export { AUTHENTICATION_REQUIRED_CODE, type AgentDefinition, type AgentSummary, type DrupalAgentOptions, DrupalOAuth, type DrupalOAuthOptions, type DrupalToolsOptions, INSUFFICIENT_SCOPE_CODE, type JsonSchema, VERSION, describeRefusal, drupalAgent, drupalTools, listAgents, normaliseSchema, promptFrom, scopeFromChallenge };