Migrate to using official MCP TS SDK (#80)

Co-authored-by: Claude <noreply@anthropic.com>

Author: quuu

.gitignore

@@ -1,8 +1,6 @@
 .DS_Store
 node_modules/
 dist/
-.xmcp/
-xmcp-env.d.ts
 .next/
 *.tsbuildinfo
 .turbo

CLAUDE.md

@@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 This is an MCP (Model Context Protocol) server that provides Next.js development tools for AI coding assistants. The server exposes tools, prompts, and resources to help with Next.js upgrades, Cache Components setup, documentation search, browser testing, and runtime diagnostics.
 
+The server is built using the standard `@modelcontextprotocol/sdk` package with TypeScript and ES modules.
+
 ## Build and Development Commands
 
 ```bash
@@ -46,15 +48,18 @@ Test files are located in `test/e2e/` and use test fixtures from `test/fixtures/
 
 ### MCP Server Structure
 
-The main server is generated by `xmcp` (configured in `xmcp.config.ts`) and uses stdio transport. The server automatically registers:
-- **Tools** (`src/tools/`): Callable functions for automation
-- **Prompts** (`src/prompts/`): Pre-configured prompts for common tasks
-- **Resources** (`src/resources/`): Knowledge base articles and documentation
+The main server entry point is `src/index.ts` which uses the standard MCP SDK with stdio transport. The server manually registers:
+- **Tools** (`src/tools/`): Callable functions for automation - each exports `inputSchema`, `metadata`, and `handler`
+- **Prompts** (`src/prompts/`): Pre-configured prompts for common tasks - each exports `inputSchema`, `metadata`, and `handler`
+- **Resources** (`src/resources/`): Knowledge base articles and documentation - each exports `metadata` and `handler`
+
+All tools, prompts, and resources are explicitly imported and registered in `src/index.ts`.
 
 ### Key Components
 
 **MCP Tools** (`src/tools/`):
-- Tools are automatically discovered and registered by xmcp from `src/tools/`
+- Each tool exports: `inputSchema` (Zod schemas), `metadata` (name, description), `handler` (async function)
+- Tools are manually imported and registered in `src/index.ts`
 - `nextjs_docs`: Search Next.js documentation and knowledge base
 - `browser_eval`: Playwright browser automation (via `playwright-mcp` server)
 - `nextjs_runtime`: Connect to Next.js dev server MCP endpoint for runtime diagnostics
@@ -71,34 +76,37 @@ The main server is generated by `xmcp` (configured in `xmcp.config.ts`) and uses
 - `nextjs-runtime-manager.ts`: Discovers and connects to Next.js dev servers with MCP enabled
 
 **Resources Architecture**:
-- Knowledge base split into focused sections (12 sections for Next.js 16)
-- Resources are loaded on-demand to avoid overwhelming context
+- Knowledge base split into focused sections (12 sections for Cache Components, 2 for Next.js 16, 1 for fundamentals)
+- Each resource exports: `metadata` (uri, name, description, mimeType) and `handler` (function returning content)
+- Resources use URI-based addressing (e.g., `cache-components://overview`)
 - Markdown files in `src/resources/` are copied to `dist/resources/` during build via `scripts/copy-resources.js`
 
 ### TypeScript Configuration
 
-- Target: ES2022, CommonJS modules
+- Target: ES2022, ES modules (Node16 module resolution)
 - Strict mode enabled
 - Output directory: `dist/`
 - Declaration files generated
+- Package marked as `"type": "module"` for native ES module support
 
 ## Build Process
 
-1. Server generation: `xmcp build` generates the MCP server from `xmcp.config.ts` configuration
+1. TypeScript compilation: `tsc` compiles all TypeScript files from `src/` to `dist/`
 2. Resource copying: `scripts/copy-resources.js` copies markdown files from `src/resources/` and `src/prompts/` to `dist/resources/`
 
-The `dist/stdio.js` file is the entry point for the MCP server and includes a shebang for CLI execution.
+The `dist/index.js` file is the entry point for the MCP server and includes a shebang for CLI execution.
 
 ## MCP Protocol Integration
 
 This server can:
-1. Act as a standalone MCP server (stdio transport)
+1. Act as a standalone MCP server (stdio transport using `@modelcontextprotocol/sdk`)
 2. Connect to other MCP servers as a client (e.g., playwright-mcp, Next.js runtime MCP)
 
 **Key MCP Patterns**:
-- Tools use Zod schemas for input validation
-- Tool handlers receive validated arguments via `tool.execute()`
-- Resources use URI-based addressing (e.g., `nextjs16://knowledge/overview`)
+- Server uses standard MCP SDK `Server` class with `StdioServerTransport`
+- Tools use Zod schemas for input validation, converted to JSON Schema for MCP
+- Tool handlers are called with validated arguments
+- Resources use URI-based addressing (e.g., `cache-components://overview`)
 - Prompts return structured messages with markdown content
 
 ## External MCP Server Dependencies
@@ -118,16 +126,29 @@ This server can:
 ## Common Development Patterns
 
 **Adding a new MCP tool**:
-1. Create tool file in `src/tools/` with Zod schema and `tool()` function
-2. xmcp automatically discovers and registers tools from `src/tools/`
+1. Create tool file in `src/tools/` with:
+   - `export const inputSchema = { ... }` - Zod schemas for each parameter
+   - `export const metadata = { name, description }`
+   - `export async function handler(args) { ... }` - Tool implementation
+2. Import and add to the `tools` array in `src/index.ts`
 3. Build and test
 
 **Adding a new MCP resource**:
 1. Create markdown file(s) in `src/resources/`
-2. Create resource handler TypeScript file in `src/resources/` with URI scheme
-3. xmcp automatically discovers and registers resources from `src/resources/`
+2. Create resource handler TypeScript file in `src/resources/` with:
+   - `export const metadata = { uri, name, description, mimeType }`
+   - `export function handler() { return readResourceFile(...) }` - Returns content
+3. Import and add to the `resources` array in `src/index.ts`
 4. The `scripts/copy-resources.js` script automatically copies `.md` files to `dist/resources/`
 
+**Adding a new MCP prompt**:
+1. Create prompt file in `src/prompts/` with:
+   - `export const inputSchema = { ... }` - Optional Zod schemas for parameters
+   - `export const metadata = { name, description, role }`
+   - `export function handler(args) { ... }` - Returns prompt text
+2. Import and add to the `prompts` array in `src/index.ts`
+3. Build and test
+
 **Working with external MCP servers**:
 - Use `src/_internal/mcp-client.ts` for stdio-based communication
 - Create manager module in `src/_internal/` for lifecycle management
@@ -136,6 +157,7 @@ This server can:
 ## Package Publishing
 
 - Package name: `next-devtools-mcp`
-- Binary: `next-devtools-mcp` points to `dist/stdio.js`
+- Package type: ES module (`"type": "module"`)
+- Binary: `next-devtools-mcp` points to `dist/index.js`
 - prepublishOnly hook: cleans and rebuilds before publishing
 - Use `pnpm@9.15.9` as package manager

package.json

@@ -1,31 +1,32 @@
 {
   "name": "next-devtools-mcp",
   "version": "0.2.6",
+  "type": "module",
   "description": "Next.js development tools MCP server with stdio transport",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/vercel/next-devtools-mcp.git"
   },
   "bin": {
-    "next-devtools-mcp": "./dist/stdio.js"
+    "next-devtools-mcp": "./dist/index.js"
   },
-  "main": "dist/stdio.js",
+  "main": "dist/index.js",
   "exports": {
     "./package.json": "./package.json",
-    ".": "./dist/stdio.js"
+    ".": "./dist/index.js"
   },
   "files": [
     "dist"
   ],
   "mcpName": "io.github.vercel/next-devtools-mcp",
   "scripts": {
-    "dev": "xmcp dev",
+    "dev": "tsc --watch",
     "copy-resources": "node scripts/copy-resources.js",
-    "build": "xmcp build && npm run copy-resources",
+    "build": "tsc && npm run copy-resources",
     "prepublishOnly": "pnpm run clean && pnpm run build",
     "clean": "rm -rf dist",
-    "start": "node dist/stdio.js",
+    "start": "node dist/index.js",
     "test": "vitest run --exclude 'test/e2e/**'",
     "test:e2e": "vitest run test/e2e",
     "eval": "vitest run test/e2e/upgrade.test.ts",
@@ -35,7 +36,6 @@
     "@modelcontextprotocol/sdk": "1.21.0",
     "find-process": "2.0.0",
     "pid-port": "2.0.0",
-    "xmcp": "0.4.0",
     "zod": "3.25.76"
   },
   "devDependencies": {