From 1391194af06d5613e6a61e3e9561dbb263ddabcb Mon Sep 17 00:00:00 2001
From: Ali Mohammad <freelancealimohammad@gmail.com>
Date: Tue, 29 Sep 2026 02:01:27 +0300
Subject: [PATCH] LOU-K1: export MCP client on public API surface

An audit found McpToolLoader / loadMcpTools() fully implemented and
tested in src/tools/mcp/ but unreachable from the public API: it was
missing from src/tools/index.ts and had no ./mcp subpath export, so
consumers could only reach it via an unsupported deep import into
dist/tools/mcp/.

- Add src/tools/mcp/index.ts barrel re-exporting loadMcpTools,
  listRemoteTools, RawMcpTool, and jsonSchemaToZod.
- Re-export it from src/tools/index.ts so it's reachable from the
  package root and @loushy/build-ai-agent/tools.
- Add a "./mcp" entry to package.json's exports map, mirroring the
  existing "./tools" shape.
- Add tools/mcp/index as an explicit tsup entry point so dist/tools/mcp/index.*
  is actually emitted.
- Document the new export with a short snippet in docs/api-overview.md
  and docs/configuration.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/api-overview.md   |  7 +++++++
 docs/configuration.md  | 17 +++++++++++++++++
 package.json           |  5 +++++
 src/tools/index.ts     |  1 +
 src/tools/mcp/index.ts | 10 ++++++++++
 tsup.config.ts         |  1 +
 6 files changed, 41 insertions(+)
 create mode 100644 src/tools/mcp/index.ts

diff --git a/docs/api-overview.md b/docs/api-overview.md
index 4082e3cd6..b7ba40c0b 100644
--- a/docs/api-overview.md
+++ b/docs/api-overview.md
@@ -42,6 +42,13 @@ npm run docs:build   # writes docs/api/index.html
 | -------------------------------------------- | --------------------------------------------- |
 | `ToolRegistry`                               | Holds the tools an agent config refers to.    |
 | `httpTool`, `currentDateTool`, `dayNameTool` | Built-in tools.                               |
+| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `@loushy/build-ai-agent/tools`, and `@loushy/build-ai-agent/mcp`. |
+
+```ts
+import { loadMcpTools } from '@loushy/build-ai-agent/mcp';
+
+const tools = await loadMcpTools(mcpClient, 'my-server');
+```
 
 ## Flows, evals, observability and security
 
diff --git a/docs/configuration.md b/docs/configuration.md
index e86a4bdb5..d34d89898 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -40,6 +40,23 @@ tools:
 them throws an error telling you to build the agent with `createAgent()` and
 pass a configured tool instead.
 
+### MCP (Model Context Protocol) tools
+
+Tools advertised by a remote MCP server aren't referenced by name in a spec
+file - connect a `Client` from `@modelcontextprotocol/sdk` yourself and load
+its tools with `loadMcpTools()`, then pass the result to `createAgent()` (or
+register it on a `ToolRegistry`):
+
+```ts
+import { loadMcpTools } from '@loushy/build-ai-agent/mcp';
+
+const tools = await loadMcpTools(mcpClient, 'my-server');
+const agent = createAgent({ prompt: '...', provider, tools });
+```
+
+`loadMcpTools` is also available from the package root and from
+`@loushy/build-ai-agent/tools`.
+
 ## Provider credentials
 
 Real providers are resolved by `resolveProvider('<provider>/<model>')`
diff --git a/package.json b/package.json
index 83b23b615..575edd421 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,11 @@
       "import": "./dist/flows/index.mjs",
       "require": "./dist/flows/index.js"
     },
+    "./mcp": {
+      "types": "./dist/tools/mcp/index.d.ts",
+      "import": "./dist/tools/mcp/index.mjs",
+      "require": "./dist/tools/mcp/index.js"
+    },
     "./types": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/types/index.mjs",
diff --git a/src/tools/index.ts b/src/tools/index.ts
index 25401b7b4..08affdd71 100644
--- a/src/tools/index.ts
+++ b/src/tools/index.ts
@@ -1,3 +1,4 @@
 export * from './ToolRegistry';
 export * from './built-in';
+export * from './mcp';
 
diff --git a/src/tools/mcp/index.ts b/src/tools/mcp/index.ts
new file mode 100644
index 000000000..192b1f613
--- /dev/null
+++ b/src/tools/mcp/index.ts
@@ -0,0 +1,10 @@
+/**
+ * MCP Tool Loader Module (LOU-K1)
+ *
+ * Public surface for loading tools advertised by a connected MCP
+ * (Model Context Protocol) server and turning them into ToolDescriptors
+ * usable elsewhere in the SDK (e.g. registered on a ToolRegistry).
+ */
+
+export * from './McpToolLoader';
+export * from './schema';
diff --git a/tsup.config.ts b/tsup.config.ts
index 97c706ad8..b39ea96d4 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -22,6 +22,7 @@ export default defineConfig({
     index: 'src/index.ts',
     'core/index': 'src/core/index.ts',
     'tools/index': 'src/tools/index.ts',
+    'tools/mcp/index': 'src/tools/mcp/index.ts',
     'flows/index': 'src/flows/index.ts',
     'data/index': 'src/data/index.ts',
     'types/index': 'src/types/index.ts',