create-mcp-use-app 0.3.1 → 0.3.3

package/README.md

@@ -0,0 +1,444 @@
+<div align="center" style="margin: 0 auto; max-width: 80%;">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mcp-use/mcp-use-ts/main/packages/mcp-use/static/logo_white.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mcp-use/mcp-use-ts/main/packages/mcp-use/static/logo_black.svg">
+    <img alt="mcp use logo" src="https://raw.githubusercontent.com/mcp-use/mcp-use-ts/main/packages/mcp-use/static/logo_white.svg" width="80%" style="margin: 20px auto;">
+  </picture>
+</div>
+
+<h1 align="center">Create MCP-Use App</h1>
+
+<p align="center">
+    <a href="https://www.npmjs.com/package/create-mcp-use-app" alt="NPM Downloads">
+        <img src="https://img.shields.io/npm/dw/create-mcp-use-app.svg"/></a>
+    <a href="https://www.npmjs.com/package/create-mcp-use-app" alt="NPM Version">
+        <img src="https://img.shields.io/npm/v/create-mcp-use-app.svg"/></a>
+    <a href="https://github.com/mcp-use/mcp-use-ts/blob/main/LICENSE" alt="License">
+        <img src="https://img.shields.io/github/license/mcp-use/mcp-use-ts" /></a>
+    <a href="https://github.com/mcp-use/mcp-use-ts/stargazers" alt="GitHub stars">
+        <img src="https://img.shields.io/github/stars/mcp-use/mcp-use-ts?style=social" /></a>
+    <a href="https://discord.gg/XkNkSkMz3V" alt="Discord">
+        <img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a>
+</p>
+
+🚀 **Create MCP-Use App** is the fastest way to scaffold a new MCP (Model Context Protocol) application. With just one command, you get a fully configured TypeScript project with hot reload, automatic inspector, and UI widget support - everything you need to build powerful MCP servers.
+
+## 📦 Related Packages
+
+| Package | Description | Version |
+|---------|-------------|---------|
+| [mcp-use](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/mcp-use) | Core MCP framework | [![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 | [![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 inspector | [![npm](https://img.shields.io/npm/v/@mcp-use/inspector.svg)](https://www.npmjs.com/package/@mcp-use/inspector) |
+
+---
+
+## ⚡ Quick Start
+
+Create a new MCP application in seconds:
+
+```bash
+npx create-mcp-use-app my-mcp-server
+cd my-mcp-server
+npm run dev
+```
+
+That's it! Your MCP server is running at `http://localhost:3000` with the inspector automatically opened in your browser.
+
+---
+
+## 🎯 What It Creates
+
+Running `create-mcp-use-app` sets up a complete MCP development environment:
+
+### Project Structure
+
+```
+my-mcp-server/
+├── package.json          # Pre-configured with all scripts
+├── tsconfig.json         # TypeScript configuration
+├── .env.example          # Environment variables template
+├── .gitignore           # Git ignore rules
+├── README.md            # Project documentation
+├── src/
+│   └── index.ts         # MCP server entry point with example tools
+├── resources/           # UI widgets directory
+│   └── example-widget.tsx  # Example React widget
+└── dist/               # Build output (generated)
+```
+
+### Pre-configured Features
+
+| Feature | Description |
+|---------|-------------|
+| **📝 TypeScript** | Full TypeScript setup with proper types |
+| **🔥 Hot Reload** | Auto-restart on code changes during development |
+| **🔍 Auto Inspector** | Inspector UI opens automatically in dev mode |
+| **🎨 UI Widgets** | React components that compile to standalone pages |
+| **🛠️ Example Tools** | Sample MCP tools, resources, and prompts |
+| **📦 Build Scripts** | Ready-to-use development and production scripts |
+| **🚀 Production Ready** | Optimized build configuration |
+
+---
+
+## 📖 Usage Options
+
+### Interactive Mode
+
+Run without any arguments to enter interactive mode:
+
+```bash
+npx create-mcp-use-app
+```
+
+You'll be prompted for:
+- Project name
+- Project template
+- Package manager preference
+
+### Direct Mode
+
+Specify the project name directly:
+
+```bash
+npx create-mcp-use-app my-project
+```
+
+### With Options
+
+```bash
+# Use a specific template
+npx create-mcp-use-app my-project --template advanced
+
+# Use a specific package manager
+npx create-mcp-use-app my-project --use-npm
+npx create-mcp-use-app my-project --use-yarn
+npx create-mcp-use-app my-project --use-pnpm
+
+# Skip dependency installation
+npx create-mcp-use-app my-project --skip-install
+```
+
+---
+
+## 🎨 Available Templates
+
+### Basic Template (Default)
+
+The basic template includes:
+- Simple MCP server setup
+- Example tool, resource, and prompt
+- Basic UI widget example
+- Essential configuration files
+
+Perfect for getting started quickly or building simple MCP servers.
+
+### Advanced Template
+
+The advanced template includes everything from basic plus:
+- Multiple tools with complex schemas
+- OAuth authentication example
+- Database integration patterns
+- Advanced UI widgets with state management
+- Observability setup with Langfuse
+- Docker configuration
+- CI/CD workflows
+
+Ideal for production applications or complex integrations.
+
+### Minimal Template
+
+The minimal template includes:
+- Bare-bones MCP server
+- No example tools or widgets
+- Essential configuration only
+
+Best for experienced developers who want full control.
+
+---
+
+## 🏗️ What Gets Installed
+
+The scaffolded project includes these dependencies:
+
+### Core Dependencies
+- `mcp-use` - The MCP framework
+- `@mcp-use/cli` - Build and development tool
+- `@mcp-use/inspector` - Web-based debugger
+
+### Development Dependencies
+- `typescript` - TypeScript compiler
+- `tsx` - TypeScript executor for development
+- `@types/node` - Node.js type definitions
+
+### Optional Dependencies (Advanced Template)
+- Database drivers (PostgreSQL, SQLite)
+- Authentication libraries
+- Monitoring tools
+
+---
+
+## 🚀 After Installation
+
+Once your project is created, you can:
+
+### Start Development
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+```
+
+This will:
+1. Start the MCP server on port 3000
+2. Open the inspector in your browser
+3. Watch for file changes and auto-reload
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+Creates an optimized build in the `dist/` directory.
+
+### Start Production Server
+
+```bash
+npm run start
+```
+
+Runs the production build.
+
+---
+
+## 💡 First Steps
+
+After creating your app, here's what to do next:
+
+### 1. Explore the Example Server
+
+Open `src/index.ts` to see how to:
+- Define MCP tools with Zod schemas
+- Create resources for data access
+- Set up prompts for AI interactions
+
+### 2. Try the Inspector
+
+The inspector automatically opens at `http://localhost:3000/inspector` where you can:
+- Test your tools interactively
+- View available resources
+- Debug tool executions
+- Monitor server status
+
+### 3. Create a UI Widget
+
+Edit `resources/example-widget.tsx` or create new widgets:
+
+```tsx
+import React from 'react'
+import { useMcp } from 'mcp-use/react'
+
+export default function MyWidget() {
+  const { callTool } = useMcp()
+
+  const handleClick = async () => {
+    const result = await callTool('my_tool', {
+      param: 'value'
+    })
+    console.log(result)
+  }
+
+  return (
+    <div>
+      <button onClick={handleClick}>
+        Call MCP Tool
+      </button>
+    </div>
+  )
+}
+```
+
+### 4. Connect to AI
+
+Use the MCP server with any MCP-compatible client:
+
+```typescript
+import { MCPClient, MCPAgent } from 'mcp-use'
+import { ChatOpenAI } from '@langchain/openai'
+
+const client = new MCPClient({
+  url: 'http://localhost:3000/mcp'
+})
+
+const agent = new MCPAgent({
+  llm: new ChatOpenAI(),
+  client
+})
+
+const result = await agent.run('Use my MCP tools')
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables
+
+The created project includes a `.env.example` file:
+
+```bash
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# OAuth (if using authentication)
+OAUTH_CLIENT_ID=your_client_id
+OAUTH_CLIENT_SECRET=your_client_secret
+
+# Database (if using database)
+DATABASE_URL=postgresql://localhost/myapp
+
+# Observability (optional)
+LANGFUSE_PUBLIC_KEY=your_public_key
+LANGFUSE_SECRET_KEY=your_secret_key
+```
+
+Copy to `.env` and configure as needed:
+
+```bash
+cp .env.example .env
+```
+
+### TypeScript Configuration
+
+The `tsconfig.json` is pre-configured for MCP development:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+---
+
+## 📚 Examples
+
+### Creating a Tool
+
+```typescript
+server.tool('search_database', {
+  description: 'Search for records in the database',
+  parameters: z.object({
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().default(10)
+  }),
+  execute: async ({ query, limit }) => {
+    // Your tool logic here
+    const results = await db.search(query, limit)
+    return { results }
+  }
+})
+```
+
+### Creating a Resource
+
+```typescript
+server.resource('user_profile', {
+  description: 'Current user profile data',
+  uri: 'user://profile',
+  mimeType: 'application/json',
+  fetch: async () => {
+    const profile = await getUserProfile()
+    return JSON.stringify(profile)
+  }
+})
+```
+
+### Creating a Prompt
+
+```typescript
+server.prompt('code_review', {
+  description: 'Review code for best practices',
+  arguments: [
+    { name: 'code', description: 'Code to review', required: true },
+    { name: 'language', description: 'Programming language', required: false }
+  ],
+  render: async ({ code, language }) => {
+    return `Please review this ${language || ''} code for best practices:\n\n${code}`
+  }
+})
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Command not found:**
+```bash
+# Make sure you have Node.js 18+ installed
+node --version
+
+# Try with npx
+npx create-mcp-use-app@latest
+```
+
+**Permission denied:**
+```bash
+# On macOS/Linux, you might need sudo
+sudo npx create-mcp-use-app my-app
+```
+
+**Network issues:**
+```bash
+# Use a different registry
+npm config set registry https://registry.npmjs.org/
+```
+
+**Port already in use:**
+```bash
+# Change the port in your .env file
+PORT=3001
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! To contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+See our [contributing guide](https://github.com/mcp-use/mcp-use-ts/blob/main/CONTRIBUTING.md) for more details.
+
+---
+
+## 📚 Learn More
+
+- [MCP-Use Documentation](https://github.com/mcp-use/mcp-use-ts)
+- [Model Context Protocol Spec](https://modelcontextprotocol.io)
+- [Creating MCP Tools](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/mcp-use#-mcp-server-framework)
+- [Building UI Widgets](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/cli#-creating-ui-widgets)
+- [Using the Inspector](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/inspector)
+
+---
+
+## 📜 License
+
+MIT © [MCP-Use](https://github.com/mcp-use)

package/dist/index.js

@@ -10,7 +10,70 @@ import { Command } from "commander";
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
 var program = new Command();
-program.name("create-mcp-use-app").description("Create a new MCP server project").version("0.1.0").argument("[project-name]", "Name of the MCP server project").option("-t, --template <template>", "Template to use", "ui").option("--no-install", "Skip installing dependencies").action(async (projectName, options) => {
+var packageJson = JSON.parse(
+  readFileSync(join(__dirname, "../package.json"), "utf-8")
+);
+function getCurrentPackageVersions() {
+  const versions = {};
+  try {
+    const possibleRoots = [
+      resolve(__dirname, "../../../.."),
+      // From dist/templates
+      resolve(__dirname, "../../../../.."),
+      // From dist
+      resolve(process.cwd(), "."),
+      // Current working directory
+      resolve(process.cwd(), "..")
+      // Parent of current directory
+    ];
+    let workspaceRoot = null;
+    for (const root of possibleRoots) {
+      if (existsSync(join(root, "packages/mcp-use/package.json"))) {
+        workspaceRoot = root;
+        break;
+      }
+    }
+    if (!workspaceRoot) {
+      throw new Error("Workspace root not found");
+    }
+    const mcpUsePackage = JSON.parse(
+      readFileSync(join(workspaceRoot, "packages/mcp-use/package.json"), "utf-8")
+    );
+    versions["mcp-use"] = mcpUsePackage.version;
+    const cliPackage = JSON.parse(
+      readFileSync(join(workspaceRoot, "packages/cli/package.json"), "utf-8")
+    );
+    versions["@mcp-use/cli"] = cliPackage.version;
+    const inspectorPackage = JSON.parse(
+      readFileSync(join(workspaceRoot, "packages/inspector/package.json"), "utf-8")
+    );
+    versions["@mcp-use/inspector"] = inspectorPackage.version;
+  } catch (error) {
+    console.warn("\u26A0\uFE0F  Could not read workspace package versions, using defaults");
+    console.warn(`   Error: ${error}`);
+  }
+  return versions;
+}
+function processTemplateFile(filePath, versions, isDevelopment = false) {
+  const content = readFileSync(filePath, "utf-8");
+  let processedContent = content;
+  for (const [packageName, version] of Object.entries(versions)) {
+    const placeholder = `{{${packageName}_version}}`;
+    const versionPrefix = isDevelopment ? "workspace:*" : `^${version}`;
+    processedContent = processedContent.replace(new RegExp(placeholder, "g"), versionPrefix);
+  }
+  if (isDevelopment) {
+    processedContent = processedContent.replace(/"mcp-use": "\^[^"]+"/, '"mcp-use": "workspace:*"');
+    processedContent = processedContent.replace(/"@mcp-use\/cli": "\^[^"]+"/, '"@mcp-use/cli": "workspace:*"');
+    processedContent = processedContent.replace(/"@mcp-use\/inspector": "\^[^"]+"/, '"@mcp-use/inspector": "workspace:*"');
+  } else {
+    processedContent = processedContent.replace(/"mcp-use": "workspace:\*"/, `"mcp-use": "^${versions["mcp-use"] || "1.0.0"}"`);
+    processedContent = processedContent.replace(/"@mcp-use\/cli": "workspace:\*"/, `"@mcp-use/cli": "^${versions["@mcp-use/cli"] || "2.0.0"}"`);
+    processedContent = processedContent.replace(/"@mcp-use\/inspector": "workspace:\*"/, `"@mcp-use/inspector": "^${versions["@mcp-use/inspector"] || "0.3.0"}"`);
+  }
+  return processedContent;
+}
+program.name("create-mcp-use-app").description("Create a new MCP server project").version(packageJson.version).argument("[project-name]", "Name of the MCP server project").option("-t, --template <template>", "Template to use", "ui").option("--no-install", "Skip installing dependencies").option("--dev", "Use workspace dependencies for development").action(async (projectName, options) => {
   try {
     if (!projectName) {
       console.log("\u{1F3AF} Welcome to create-mcp-use-app!");
@@ -29,7 +92,8 @@ program.name("create-mcp-use-app").description("Create a new MCP server project"
       process.exit(1);
     }
     mkdirSync(projectPath, { recursive: true });
-    await copyTemplate(projectPath, options.template);
+    const versions = getCurrentPackageVersions();
+    await copyTemplate(projectPath, options.template, versions, options.dev);
     updatePackageJson(projectPath, projectName);
     if (options.install) {
       console.log("\u{1F4E6} Installing dependencies...");
@@ -45,6 +109,9 @@ program.name("create-mcp-use-app").description("Create a new MCP server project"
       }
     }
     console.log("\u2705 MCP server created successfully!");
+    if (options.dev) {
+      console.log("\u{1F527} Development mode: Using workspace dependencies");
+    }
     console.log("");
     console.log("\u{1F4C1} Project structure:");
     console.log(`   ${projectName}/`);
@@ -55,6 +122,7 @@ program.name("create-mcp-use-app").description("Create a new MCP server project"
       console.log("   \u2502   \u251C\u2500\u2500 data-visualization.tsx");
       console.log("   \u2502   \u251C\u2500\u2500 kanban-board.tsx");
       console.log("   \u2502   \u2514\u2500\u2500 todo-list.tsx");
+      console.log("   \u251C\u2500\u2500 index.ts");
       console.log("   \u251C\u2500\u2500 package.json");
       console.log("   \u251C\u2500\u2500 tsconfig.json");
       console.log("   \u2514\u2500\u2500 README.md");
@@ -73,13 +141,17 @@ program.name("create-mcp-use-app").description("Create a new MCP server project"
     }
     console.log("   npm run dev");
     console.log("");
+    if (options.dev) {
+      console.log("\u{1F4A1} Development mode: Your project uses workspace dependencies");
+      console.log("   Make sure you're in the mcp-use workspace root for development");
+    }
     console.log("\u{1F4DA} Learn more: https://docs.mcp-use.io");
   } catch (error) {
     console.error("\u274C Error creating MCP server:", error);
     process.exit(1);
   }
 });
-async function copyTemplate(projectPath, template) {
+async function copyTemplate(projectPath, template, versions, isDevelopment = false) {
   const templatePath = join(__dirname, "templates", template);
   if (!existsSync(templatePath)) {
     console.error(`\u274C Template "${template}" not found!`);
@@ -87,27 +159,32 @@ async function copyTemplate(projectPath, template) {
     console.log('\u{1F4A1} Tip: Use "ui" template for React components and modern UI features');
     process.exit(1);
   }
-  copyDirectory(templatePath, projectPath);
+  copyDirectoryWithProcessing(templatePath, projectPath, versions, isDevelopment);
 }
-function copyDirectory(src, dest) {
+function copyDirectoryWithProcessing(src, dest, versions, isDevelopment) {
   const entries = readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = join(src, entry.name);
     const destPath = join(dest, entry.name);
     if (entry.isDirectory()) {
       mkdirSync(destPath, { recursive: true });
-      copyDirectory(srcPath, destPath);
+      copyDirectoryWithProcessing(srcPath, destPath, versions, isDevelopment);
     } else {
-      copyFileSync(srcPath, destPath);
+      if (entry.name === "package.json" || entry.name.endsWith(".json")) {
+        const processedContent = processTemplateFile(srcPath, versions, isDevelopment);
+        writeFileSync(destPath, processedContent);
+      } else {
+        copyFileSync(srcPath, destPath);
+      }
     }
   }
 }
 function updatePackageJson(projectPath, projectName) {
   const packageJsonPath = join(projectPath, "package.json");
-  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-  packageJson.name = projectName;
-  packageJson.description = `MCP server: ${projectName}`;
-  writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+  const packageJsonContent = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  packageJsonContent.name = projectName;
+  packageJsonContent.description = `MCP server: ${projectName}`;
+  writeFileSync(packageJsonPath, JSON.stringify(packageJsonContent, null, 2));
 }
 function promptForProjectName() {
   return new Promise((resolvePromise) => {

package/dist/templates/ui/README.md

@@ -234,29 +234,29 @@ if (container) {
 npm run build
 
 # The built files will be in dist/
-# - dist/server.js (MCP server)
-# - dist/resources/ (UI widgets)
+# - dist/index.js (MCP server entry point)
+# - dist/src/server.js (MCP server implementation)  
+# - dist/resources/ (Compiled TypeScript + UI widget bundles)
 ```
 
 ## Project Structure
 
 ```
 my-ui-server/
+├── index.ts                   # Entry point (re-exports server)
 ├── src/
 │   └── server.ts              # MCP server with UI endpoints
-├── resources/                 # React components and HTML entry points
-│   ├── kanban-board.html
+├── resources/                 # React components (TSX widgets)
 │   ├── kanban-board.tsx
-│   ├── todo-list.html
 │   ├── todo-list.tsx
-│   ├── data-visualization.html
 │   └── data-visualization.tsx
 ├── dist/                      # Built files
-│   ├── server.js
-│   └── resources/
+│   ├── index.js               # Entry point
+│   ├── src/
+│   │   └── server.js          # Server implementation
+│   └── resources/             # TypeScript output + bundled widgets
 ├── package.json
 ├── tsconfig.json
-├── vite.config.ts
 └── README.md
 ```
 

package/dist/templates/ui/index.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP Server Entry Point
+ * 
+ * This file serves as the main entry point for the MCP server application.
+ * It re-exports all functionality from the server implementation, allowing
+ * the CLI and other tools to locate and start the server.
+ * 
+ * The server is automatically started when this module is imported, making
+ * it suitable for both direct execution and programmatic usage.
+ */
+export * from './src/server.js'
+

package/dist/templates/ui/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "test-ui",
+  "name": "mcp-use-server-with-mcp-ui",
   "type": "module",
   "version": "1.0.0",
-  "description": "MCP server: test-ui",
+  "description": "MCP server: mcp-use-server-with-mcp-ui",
   "author": "",
   "license": "MIT",
   "keywords": [
@@ -14,7 +14,7 @@
     "ai",
     "tools"
   ],
-  "main": "dist/server.js",
+  "main": "dist/index.js",
   "scripts": {
     "build": "mcp-use build",
     "dev": "mcp-use dev",
@@ -24,10 +24,11 @@
     "@mcp-ui/server": "^5.11.0",
     "cors": "^2.8.5",
     "express": "^4.18.0",
-    "mcp-use": "^0.3.0"
+    "mcp-use": "workspace:*"
   },
   "devDependencies": {
-    "@mcp-use/cli": "^2.0.2",
+    "@mcp-use/cli": "workspace:*",
+    "@mcp-use/inspector": "workspace:*",
     "@types/cors": "^2.8.0",
     "@types/express": "^4.17.0",
     "@types/node": "^20.0.0",

package/dist/templates/ui/resources/kanban-board.tsx

@@ -16,7 +16,7 @@ interface KanbanBoardProps {
 
 const KanbanBoard: React.FC<KanbanBoardProps> = ({ initialTasks = [] }) => {
   const [tasks, setTasks] = useState<Task[]>(initialTasks)
-  const [newTask, setNewTask] = useState({ title: '', description: '', priority: 'medium' as const })
+  const [newTask, setNewTask] = useState({ title: '', description: '', priority: 'medium' as Task['priority'] })
 
   // Load tasks from URL parameters or use defaults
   useEffect(() => {