mcp-use 1.0.0 → 1.0.2

package/README.md

@@ -27,9 +27,18 @@
         <img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a>
 </p>
 
-🌐 **MCP Client** is the open-source way to connect **any LLM to any MCP server** in TypeScript/Node.js, letting you build custom agents with tool access without closed-source dependencies.
+🌐 **MCP-Use** is a complete TypeScript framework for building and using MCP (Model Context Protocol) applications. It provides both a powerful **client library** for connecting LLMs to MCP servers and a **server framework** for building your own MCP servers with UI capabilities.
 
-💡 Let developers easily connect any LLM via LangChain.js to tools like web browsing, file operations, 3D modeling, and more.
+💡 Build custom AI agents, create MCP servers with React UI widgets, and debug everything with the built-in inspector - all in TypeScript.
+
+## 📦 MCP-Use Ecosystem
+
+| Package | Description | Version |
+|---------|-------------|---------|
+| **mcp-use** | Core framework for MCP clients and servers | [![npm](https://img.shields.io/npm/v/mcp-use.svg)](https://www.npmjs.com/package/mcp-use) |
+| [@mcp-use/cli](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/cli) | Build tool for MCP apps with UI widgets | [![npm](https://img.shields.io/npm/v/@mcp-use/cli.svg)](https://www.npmjs.com/package/@mcp-use/cli) |
+| [@mcp-use/inspector](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/inspector) | Web-based MCP server inspector and debugger | [![npm](https://img.shields.io/npm/v/@mcp-use/inspector.svg)](https://www.npmjs.com/package/@mcp-use/inspector) |
+| [create-mcp-use-app](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/create-mcp-use-app) | Create MCP apps with one command | [![npm](https://img.shields.io/npm/v/create-mcp-use-app.svg)](https://www.npmjs.com/package/create-mcp-use-app) |
 
 ---
 
@@ -455,6 +464,185 @@ const agent = new MCPAgent({
 })
 ```
 
+---
+
+## 🖥️ MCP Server Framework
+
+Beyond being a powerful MCP client, mcp-use also provides a complete server framework for building your own MCP servers with built-in UI capabilities and automatic inspector integration.
+
+### Quick Server Setup
+
+```ts
+import { createMCPServer } from 'mcp-use/server'
+
+// Create your MCP server
+const server = createMCPServer('my-awesome-server', {
+  version: '1.0.0',
+  description: 'My MCP server with tools, resources, and prompts'
+})
+
+// Define tools
+server.tool('search_web', {
+  description: 'Search the web for information',
+  parameters: z.object({
+    query: z.string().describe('Search query')
+  }),
+  execute: async (args) => {
+    // Your tool implementation
+    return { results: await performSearch(args.query) }
+  }
+})
+
+// Define resources
+server.resource('config', {
+  description: 'Application configuration',
+  uri: 'config://settings',
+  mimeType: 'application/json',
+  fetch: async () => {
+    return JSON.stringify(await getConfig(), null, 2)
+  }
+})
+
+// Define prompts
+server.prompt('code_review', {
+  description: 'Review code for best practices',
+  arguments: [
+    { name: 'code', description: 'Code to review', required: true }
+  ],
+  render: async (args) => {
+    return `Please review this code:\n\n${args.code}`
+  }
+})
+
+// Start the server
+server.listen(3000)
+// 🎉 Inspector automatically available at http://localhost:3000/inspector
+// 🚀 MCP endpoint available at http://localhost:3000/mcp
+```
+
+### Key Server Features
+
+| Feature | Description |
+|---------|-------------|
+| **🔍 Auto Inspector** | Inspector UI automatically mounts at `/inspector` for debugging |
+| **🎨 UI Widgets** | Build custom React UI components served alongside your MCP tools |
+| **🔐 OAuth Support** | Built-in OAuth flow handling for secure authentication |
+| **📡 Multiple Transports** | HTTP/SSE and WebSocket support out of the box |
+| **🛠️ TypeScript First** | Full TypeScript support with type inference |
+| **♻️ Hot Reload** | Development mode with automatic reloading |
+| **📊 Observability** | Built-in logging and monitoring capabilities |
+
+### Building UI Widgets
+
+MCP-Use supports building custom UI widgets for your MCP tools using React:
+
+```tsx
+// resources/task-manager.tsx
+import React, { useState } from 'react'
+import { useMcp } from 'mcp-use/react'
+
+export default function TaskManager() {
+  const { callTool } = useMcp()
+  const [tasks, setTasks] = useState<Task[]>([])
+
+  const addTask = async (title: string) => {
+    const result = await callTool('create_task', { title })
+    setTasks([...tasks, result])
+  }
+
+  return (
+    <div>
+      <h1>Task Manager</h1>
+      {/* Your UI implementation */}
+    </div>
+  )
+}
+```
+
+Build and serve widgets using the MCP-Use CLI:
+
+```bash
+# Development with hot reload and auto-open inspector
+npx @mcp-use/cli dev
+
+# Production build
+npx @mcp-use/cli build
+
+# Start production server
+npx @mcp-use/cli start
+```
+
+### Advanced Server Configuration
+
+```ts
+const server = createMCPServer('advanced-server', {
+  version: '1.0.0',
+  description: 'Advanced MCP server with custom configuration',
+  // Custom inspector path (default: /inspector)
+  inspectorPath: '/debug',
+  // Custom MCP endpoint (default: /mcp)
+  mcpPath: '/api/mcp',
+  // Enable CORS for browser access
+  cors: {
+    origin: ['http://localhost:3000', 'https://myapp.com'],
+    credentials: true
+  },
+  // OAuth configuration
+  oauth: {
+    clientId: process.env.OAUTH_CLIENT_ID,
+    clientSecret: process.env.OAUTH_CLIENT_SECRET,
+    authorizationUrl: 'https://api.example.com/oauth/authorize',
+    tokenUrl: 'https://api.example.com/oauth/token',
+    scopes: ['read', 'write']
+  },
+  // Custom middleware
+  middleware: [
+    authenticationMiddleware,
+    rateLimitingMiddleware
+  ]
+})
+```
+
+### Server Deployment
+
+Deploy your MCP server to any Node.js hosting platform:
+
+```bash
+# Build for production
+npm run build
+
+# Start with PM2
+pm2 start dist/index.js --name mcp-server
+
+# Docker deployment
+docker build -t my-mcp-server .
+docker run -p 3000:3000 my-mcp-server
+```
+
+### Integration with Express
+
+You can also integrate MCP server into existing Express applications:
+
+```ts
+import express from 'express'
+import { mountMCPServer } from 'mcp-use/server'
+
+const app = express()
+
+// Your existing routes
+app.get('/api/health', (req, res) => res.send('OK'))
+
+// Mount MCP server
+const mcpServer = createMCPServer('integrated-server', { /* ... */ })
+mountMCPServer(app, mcpServer, {
+  basePath: '/mcp-service'  // Optional custom base path
+})
+
+app.listen(3000)
+// Inspector at: http://localhost:3000/mcp-service/inspector
+// MCP endpoint: http://localhost:3000/mcp-service/mcp
+```
+
 ## 👥 Contributors
 
 <table>

package/dist/{chunk-4DEFXVWT.js → chunk-CWWNPIJZ.js}

@@ -1,6 +1,6 @@
 import {
   BrowserOAuthClientProvider
-} from "./chunk-YUSC6R6V.js";
+} from "./chunk-TJXUCAST.js";
 import {
   __name
 } from "./chunk-SHUYVCID.js";
@@ -160,7 +160,7 @@ function useMcp(options) {
     }
     if (!clientRef.current) {
       clientRef.current = new Client(
-        { name: clientConfig.name || "use-mcp-react-client", version: clientConfig.version || "0.1.0" },
+        { name: clientConfig.name || "mcp-use", version: clientConfig.version || "0.1.0" },
         { capabilities: {} }
       );
       addLog("debug", "MCP Client initialized in connect.");

package/dist/{chunk-JXLQRAW2.js → chunk-MZPKOZE4.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-SHUYVCID.js";
 
 // src/server/mcp-server.ts
-import { McpServer as OfficialMcpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer as OfficialMcpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import express from "express";
 import { existsSync, readdirSync } from "fs";
@@ -67,6 +67,7 @@ var McpServer = class {
       version: config.version
     });
     this.app = express();
+    this.app.use(express.json());
     this.app.use((req, res, next) => {
       res.header("Access-Control-Allow-Origin", "*");
       res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
@@ -95,7 +96,10 @@ var McpServer = class {
    * @param resourceDefinition - Configuration object containing resource metadata and handler function
    * @param resourceDefinition.name - Unique identifier for the resource
    * @param resourceDefinition.uri - URI pattern for accessing the resource
-   * @param resourceDefinition.resource - Resource metadata (mime type, description, etc.)
+   * @param resourceDefinition.title - Optional human-readable title for the resource
+   * @param resourceDefinition.description - Optional description of the resource
+   * @param resourceDefinition.mimeType - MIME type of the resource content
+   * @param resourceDefinition.annotations - Optional annotations (audience, priority, lastModified)
    * @param resourceDefinition.fn - Async function that returns the resource content
    * @returns The server instance for method chaining
    * 
@@ -104,8 +108,20 @@ var McpServer = class {
    * server.resource({
    *   name: 'config',
    *   uri: 'config://app-settings',
-   *   resource: { mimeType: 'application/json' },
-   *   fn: async () => ({ theme: 'dark', language: 'en' })
+   *   title: 'Application Settings',
+   *   mimeType: 'application/json',
+   *   description: 'Current application configuration',
+   *   annotations: {
+   *     audience: ['user'],
+   *     priority: 0.8
+   *   },
+   *   fn: async () => ({
+   *     contents: [{
+   *       uri: 'config://app-settings',
+   *       mimeType: 'application/json',
+   *       text: JSON.stringify({ theme: 'dark', language: 'en' })
+   *     }]
+   *   })
    * })
    * ```
    */
@@ -113,7 +129,13 @@ var McpServer = class {
     this.server.resource(
       resourceDefinition.name,
       resourceDefinition.uri,
-      resourceDefinition.resource,
+      {
+        name: resourceDefinition.name,
+        title: resourceDefinition.title,
+        description: resourceDefinition.description,
+        mimeType: resourceDefinition.mimeType,
+        annotations: resourceDefinition.annotations
+      },
       async () => {
         return await resourceDefinition.fn();
       }
@@ -122,18 +144,76 @@ var McpServer = class {
   }
   /**
    * Define a dynamic resource template with parameters
+   * 
+   * Registers a parameterized resource template with the MCP server. Templates use URI
+   * patterns with placeholders that can be filled in at request time, allowing dynamic
+   * resource generation based on parameters.
+   * 
+   * @param resourceTemplateDefinition - Configuration object for the resource template
+   * @param resourceTemplateDefinition.name - Unique identifier for the template
+   * @param resourceTemplateDefinition.resourceTemplate - ResourceTemplate object with uriTemplate and metadata
+   * @param resourceTemplateDefinition.fn - Async function that generates resource content from URI and params
+   * @returns The server instance for method chaining
+   * 
+   * @example
+   * ```typescript
+   * server.resourceTemplate({
+   *   name: 'user-profile',
+   *   resourceTemplate: {
+   *     uriTemplate: 'user://{userId}/profile',
+   *     name: 'User Profile',
+   *     mimeType: 'application/json'
+   *   },
+   *   fn: async (uri, params) => ({
+   *     contents: [{
+   *       uri: uri.toString(),
+   *       mimeType: 'application/json',
+   *       text: JSON.stringify({ userId: params.userId, name: 'John Doe' })
+   *     }]
+   *   })
+   * })
+   * ```
    */
-  // TODO implement, for some freaky reason this give errors
-  // resourceTemplate(resourceTemplateDefinition: ResourceTemplateDefinition): this {
-  //   this.server.resource(
-  //     resourceTemplateDefinition.name,
-  //     resourceTemplateDefinition.resourceTemplate,
-  //     async (uri, params) => {
-  //       return await resourceTemplateDefinition.fn(uri, params)
-  //     },
-  //   )
-  //   return this
-  // }
+  resourceTemplate(resourceTemplateDefinition) {
+    const template = new ResourceTemplate(
+      resourceTemplateDefinition.resourceTemplate.uriTemplate,
+      {
+        list: void 0,
+        // Optional: callback to list all matching resources
+        complete: void 0
+        // Optional: callback for auto-completion
+      }
+    );
+    const metadata = {};
+    if (resourceTemplateDefinition.resourceTemplate.name) {
+      metadata.name = resourceTemplateDefinition.resourceTemplate.name;
+    }
+    if (resourceTemplateDefinition.title) {
+      metadata.title = resourceTemplateDefinition.title;
+    }
+    if (resourceTemplateDefinition.description || resourceTemplateDefinition.resourceTemplate.description) {
+      metadata.description = resourceTemplateDefinition.description || resourceTemplateDefinition.resourceTemplate.description;
+    }
+    if (resourceTemplateDefinition.resourceTemplate.mimeType) {
+      metadata.mimeType = resourceTemplateDefinition.resourceTemplate.mimeType;
+    }
+    if (resourceTemplateDefinition.annotations) {
+      metadata.annotations = resourceTemplateDefinition.annotations;
+    }
+    this.server.resource(
+      resourceTemplateDefinition.name,
+      template,
+      metadata,
+      async (uri) => {
+        const params = this.parseTemplateUri(
+          resourceTemplateDefinition.resourceTemplate.uriTemplate,
+          uri.toString()
+        );
+        return await resourceTemplateDefinition.fn(uri, params);
+      }
+    );
+    return this;
+  }
   /**
    * Define a tool that can be called by clients
    * 
@@ -515,6 +595,39 @@ var McpServer = class {
     const matches = uriTemplate.match(/\{([^}]+)\}/g);
     return matches ? matches.map((match) => match.slice(1, -1)) : [];
   }
+  /**
+   * Parse parameter values from a URI based on a template
+   * 
+   * Extracts parameter values from an actual URI by matching it against a URI template.
+   * The template contains placeholders like {param} which are extracted as key-value pairs.
+   * 
+   * @param template - URI template with placeholders (e.g., "user://{userId}/posts/{postId}")
+   * @param uri - Actual URI to parse (e.g., "user://123/posts/456")
+   * @returns Object mapping parameter names to their values
+   * 
+   * @example
+   * ```typescript
+   * const params = this.parseTemplateUri("user://{userId}/posts/{postId}", "user://123/posts/456")
+   * // Returns: { userId: "123", postId: "456" }
+   * ```
+   */
+  parseTemplateUri(template, uri) {
+    const params = {};
+    let regexPattern = template.replace(/[.*+?^$()[\]\\|]/g, "\\$&");
+    const paramNames = [];
+    regexPattern = regexPattern.replace(/\\\{([^}]+)\\\}/g, (_, paramName) => {
+      paramNames.push(paramName);
+      return "([^/]+)";
+    });
+    const regex = new RegExp(`^${regexPattern}$`);
+    const match = uri.match(regex);
+    if (match) {
+      paramNames.forEach((paramName, index) => {
+        params[paramName] = match[index + 1];
+      });
+    }
+    return params;
+  }
 };
 function createMCPServer(name, config = {}) {
   const instance = new McpServer({
@@ -527,6 +640,5 @@ function createMCPServer(name, config = {}) {
 __name(createMCPServer, "createMCPServer");
 
 export {
-  McpServer,
   createMCPServer
 };

package/dist/{chunk-YUSC6R6V.js → chunk-TJXUCAST.js}

@@ -20,7 +20,7 @@ var BrowserOAuthClientProvider = class {
     this.serverUrl = serverUrl;
     this.storageKeyPrefix = options.storageKeyPrefix || "mcp:auth";
     this.serverUrlHash = this.hashString(serverUrl);
-    this.clientName = options.clientName || "MCP Browser Client";
+    this.clientName = options.clientName || "mcp-use";
     this.clientUri = options.clientUri || (typeof window !== "undefined" ? window.location.origin : "");
     this.callbackUrl = sanitizeUrl(
       options.callbackUrl || (typeof window !== "undefined" ? new URL("/oauth/callback", window.location.origin).toString() : "/oauth/callback")