toolpack-sdk 1.1.0 → 1.2.0-SNAPSHOT.04032026-2

package/README.md

@@ -18,6 +18,7 @@ A unified TypeScript/Node.js SDK for building AI-powered applications with multi
 - **Mode System** — Built-in Agent and Chat modes, plus `createMode()` for custom modes with tool filtering
 - **Custom Providers** — Bring your own provider by implementing the `ProviderAdapter` interface
 - **77 Built-in Tools** across 10 categories:
+- **MCP Tool Server Integration** — dynamically bridge external Model Context Protocol servers into Toolpack as first-class tools via `createMcpToolProject()` and `disconnectMcpToolProject()`.
 
 | Category | Tools | Description |
 |----------|-------|-------------|
@@ -116,6 +117,47 @@ const sdk = await Toolpack.init({
 
 - **OpenAI**: Supports `reasoningTier` and `costTier` on model info for GPT-5.x reasoning models. API key read from `OPENAI_API_KEY` or `TOOLPACK_OPENAI_KEY`.
 - **Anthropic**: Does not support embeddings. Tool results are converted to `tool_result` content blocks automatically. `tool_choice: none` is handled by omitting tools from the request. `max_tokens` defaults to `4096` if not specified. API key read from `ANTHROPIC_API_KEY` or `TOOLPACK_ANTHROPIC_KEY`.
+
+## MCP Tool Server Support
+
+Toolpack now includes first-class support for Model Context Protocol (MCP) adapters and server tool discovery.
+
+### Quick MCP Setup
+
+```typescript
+import { Toolpack } from 'toolpack-sdk';
+import { createMcpToolProject } from './tools/mcp-tools';
+
+const mcpToolProject = await createMcpToolProject({
+  servers: [
+    {
+      name: 'filesystem',
+      displayName: 'MCP Filesystem',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
+      autoConnect: true,
+    },
+    {
+      name: 'custom',
+      displayName: 'Custom MCP',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-tools'],
+      autoConnect: true,
+    },
+  ],
+});
+
+const sdk = await Toolpack.init({
+  provider: 'openai',
+  tools: true,
+  customTools: [mcpToolProject],
+});
+
+// On shutdown/cold path:
+// await disconnectMcpToolProject(mcpToolProject);
+```
+
+See `docs/MCP_INTEGRATION.md` and `docs/examples/mcp-integration-example.ts` for full instructions and best practices.
 - **Gemini**: Uses synthetic tool call IDs (`gemini_<timestamp>_<random>`) since the Gemini API doesn't return tool call IDs natively. Tool results are converted to `functionResponse` parts in chat history automatically. API key read from `GOOGLE_GENERATIVE_AI_KEY` or `TOOLPACK_GEMINI_KEY`.
 - **Ollama**: Auto-discovers all locally pulled models when registered as `{ ollama: {} }`. Uses `/api/show` and tool probing to detect capabilities (tool calling, vision, embeddings) per model. Models without tool support are automatically stripped of tools and given a system instruction to prevent hallucinated tool usage. Uses synthetic tool call IDs (`ollama_<timestamp>_<random>`). Embeddings use the modern `/api/embed` batch endpoint. Legacy per-model registration (`{ 'ollama-llama3': {} }`) is also supported.
 
@@ -206,7 +248,7 @@ const reviewMode = createMode({
   name: 'review',
   displayName: 'Code Review',
   systemPrompt: 'You are a senior code reviewer. Read files but NEVER modify them.',
-  allowedToolCategories: ['filesystem', 'coding', 'git'],
+  allowedToolCategories: ['filesystem', 'coding', 'version-control'],
   blockedTools: ['fs.write_file', 'fs.delete_file', 'fs.append_file'],
   baseContext: {
     includeWorkingDirectory: true,
@@ -443,117 +485,6 @@ const sdk = await Toolpack.init({
 | `tools` | ToolDefinition[] | ✓ | Array of tool definitions |
 | `dependencies` | Record<string, string> | | npm dependencies (validated at load) |
 
-## Knowledge Module (RAG)
-
-The Knowledge module provides **Retrieval-Augmented Generation (RAG)** capabilities, enabling AI agents to search and retrieve relevant information from your documents during conversations.
-
-### Quick Start
-
-```typescript
-import {
-  Toolpack,
-  Knowledge,
-  MemoryProvider,
-  MarkdownSource,
-} from 'toolpack-sdk';
-
-// 1. Create a knowledge base from your documents
-const kb = await Knowledge.create({
-  provider: new MemoryProvider(),
-  source: new MarkdownSource('./docs'),  // Directory or glob pattern
-});
-
-// 2. Initialize Toolpack with knowledge
-const toolpack = await Toolpack.init({
-  provider: 'openai',
-  knowledge: kb,
-});
-
-// 3. AI automatically searches the knowledge base when needed
-const response = await toolpack.generate({
-  messages: [{ role: 'user', content: 'What does the documentation say about authentication?' }]
-});
-```
-
-When you provide a `knowledge` option, the SDK automatically:
-- Registers a `knowledge_search` tool
-- Adds it to `alwaysLoadedTools` for all modes
-- The AI calls it whenever it needs to retrieve information
-
-### Components
-
-| Component | Purpose | Options |
-|-----------|---------|---------|
-| **Sources** | Load and chunk content | `MarkdownSource`, `JSONSource`, `SQLiteTextSource` |
-| **Embedders** | Convert text to vectors | `OllamaEmbedder`, `OpenAIEmbedder`, `GeminiEmbedder` |
-| **Providers** | Store and query vectors | `MemoryProvider` |
-
-### Sources
-
-```typescript
-// Markdown files (auto-appends **/*.md if directory)
-new MarkdownSource('./docs')
-new MarkdownSource('./docs/**/*.md', { namespace: 'docs', watch: true })
-
-// JSON files
-new JSONSource('./data/products.json', {
-  chunkBy: 'item',
-  contentFields: ['name', 'description'],
-  metadataFields: ['id', 'category'],
-})
-
-// SQLite databases
-new SQLiteTextSource('./data/articles.db', {
-  table: 'articles',
-  contentColumns: ['title', 'body'],
-  metadataColumns: ['id', 'author'],
-})
-```
-
-### Embedders
-
-By default, `Knowledge.create()` auto-detects an available embedder:
-1. **Ollama** (if running locally)
-2. **OpenAI** (if `TOOLPACK_OPENAI_KEY` or `OPENAI_API_KEY` is set)
-
-```typescript
-// Explicit embedder
-const kb = await Knowledge.create({
-  provider: new MemoryProvider(),
-  source: new MarkdownSource('./docs'),
-  embedder: new OpenAIEmbedder({ model: 'text-embedding-3-small' }),
-});
-```
-
-### Direct Query
-
-```typescript
-const results = await kb.query('authentication flow', {
-  limit: 5,
-  threshold: 0.3,  // Minimum similarity (0-1)
-  filter: { type: 'documentation' },
-});
-
-for (const result of results) {
-  console.log(`Score: ${result.score}`);
-  console.log(`Content: ${result.chunk.content}`);
-}
-```
-
-### Multiple Sources
-
-```typescript
-const kb = await Knowledge.create({
-  provider: new MemoryProvider(),
-  sources: [
-    new MarkdownSource('./docs', { namespace: 'docs' }),
-    new JSONSource('./data/faq.json', { namespace: 'faq' }),
-  ],
-});
-```
-
-For complete documentation, see the [Knowledge Module Guide](./documentation/docs/guides/knowledge.md).
-
 ## Multimodal Support
 
 The SDK supports multimodal inputs (text + images) across all vision-capable providers. Images can be provided in three formats:

package/dist/client/base-agent-context.d.ts

@@ -13,4 +13,3 @@ export interface AgentContextOptions {
  * regardless of the active mode or consumer configuration.
  */
 export declare function generateBaseAgentContext(options: AgentContextOptions): string;
-//# sourceMappingURL=base-agent-context.d.ts.map

package/dist/client/base-agent-context.js

@@ -1,26 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateBaseAgentContext = generateBaseAgentContext;
-/**
- * Generates the base agent context string that is always injected into the system prompt.
- * This gives the AI baseline awareness of its environment and tools, ensuring proactive behavior
- * regardless of the active mode or consumer configuration.
- */
-function generateBaseAgentContext(options) {
-    if (options.disabled) {
-        return '';
-    }
-    const includeWd = options.includeWorkingDirectory !== false;
-    const includeCategories = options.includeToolCategories !== false;
-    const wdLine = includeWd ? `\nWorking directory: ${options.workingDirectory}` : '';
-    const categoriesList = includeCategories && options.toolCategories.length > 0
-        ? `\nAvailable tool categories: ${options.toolCategories.join(', ')}`
-        : '';
-    return `You are an AI assistant with access to tools that let you interact with the user's system.${wdLine}${categoriesList}
+"use strict";var i=Object.defineProperty;var o=(e,t)=>i(e,"name",{value:t,configurable:!0});Object.defineProperty(exports,"__esModule",{value:!0}),exports.generateBaseAgentContext=s;function s(e){if(e.disabled)return"";const t=e.includeWorkingDirectory!==!1,r=e.includeToolCategories!==!1,n=t?`
+Working directory: ${e.workingDirectory}`:"",a=r&&e.toolCategories.length>0?`
+Available tool categories: ${e.toolCategories.join(", ")}`:"";return`You are an AI assistant with access to tools that let you interact with the user's system.${n}${a}
 
 When the user asks you to do something, be proactive:
 - Use your tools to find information rather than asking the user for details you can discover yourself
 - Read files, list directories, and explore the codebase when asked to analyze or understand a project
-- Only ask the user for clarification when you genuinely cannot determine their intent or lack the required tools`;
-}
-//# sourceMappingURL=base-agent-context.js.map
+- Only ask the user for clarification when you genuinely cannot determine their intent or lack the required tools`}o(s,"generateBaseAgentContext");

package/dist/client/index.d.ts

@@ -140,4 +140,3 @@ export declare class AIClient extends EventEmitter {
     private executeToolSearch;
     private wrapError;
 }
-//# sourceMappingURL=index.d.ts.map