Introduction to MCP: A Beginner's Quickstart Guide

# Create project directory
mkdir mcp-hello-world
cd mcp-hello-world
 
# Initialize Node.js project
npm init -y

# Install MCP SDK and Zod for validation
npm install @modelcontextprotocol/sdk zod
 
# Install TypeScript development dependencies
npm install -D typescript @types/node

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

{
  "name": "mcp-hello-world",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  }
}

mkdir src

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
 
// Define input validation schema for our tool
const GreetingSchema = z.object({
  name: z.string().describe("The name of the person to greet"),
});
 
// Create the MCP server instance
const server = new Server(
  {
    name: "hello-world-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
 
// Handler: List available tools
// This tells AI clients what tools are available
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "greet",
        description: "Generate a friendly greeting for a person",
        inputSchema: {
          type: "object",
          properties: {
            name: {
              type: "string",
              description: "The name of the person to greet",
            },
          },
          required: ["name"],
        },
      },
      {
        name: "get_current_time",
        description: "Get the current date and time",
        inputSchema: {
          type: "object",
          properties: {},
          required: [],
        },
      },
    ],
  };
});
 
// Handler: Execute tool calls
// This runs when the AI wants to use a tool
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
 
  if (name === "greet") {
    // Validate the input
    const { name: personName } = GreetingSchema.parse(args);
 
    // Generate the greeting
    const greeting = `Hello, ${personName}! Welcome to the world of MCP. 🎉`;
 
    return {
      content: [
        {
          type: "text",
          text: greeting,
        },
      ],
    };
  }
 
  if (name === "get_current_time") {
    const now = new Date();
    const timeString = now.toLocaleString("en-US", {
      weekday: "long",
      year: "numeric",
      month: "long",
      day: "numeric",
      hour: "2-digit",
      minute: "2-digit",
      second: "2-digit",
      timeZoneName: "short",
    });
 
    return {
      content: [
        {
          type: "text",
          text: `The current time is: ${timeString}`,
        },
      ],
    };
  }
 
  throw new Error(`Unknown tool: ${name}`);
});
 
// Main function to start the server
async function main() {
  // Create a stdio transport (communicates via stdin/stdout)
  const transport = new StdioServerTransport();
 
  // Connect the server to the transport
  await server.connect(transport);
 
  // Log startup (to stderr so it doesn't interfere with protocol)
  console.error("MCP Hello World Server is running!");
}
 
// Start the server
main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

npm run build

# Run the server (press Ctrl+C to exit)
npm start

{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-hello-world/build/index.js"]
    }
  }
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { spawn } from "child_process";
 
async function testServer() {
  // Spawn the server process
  const serverProcess = spawn("node", ["build/index.js"], {
    stdio: ["pipe", "pipe", "inherit"],
  });
 
  // Create client transport
  const transport = new StdioClientTransport({
    reader: serverProcess.stdout!,
    writer: serverProcess.stdin!,
  });
 
  // Create and connect client
  const client = new Client({
    name: "test-client",
    version: "1.0.0",
  }, {
    capabilities: {},
  });
 
  await client.connect(transport);
 
  // List available tools
  console.log("Available tools:");
  const tools = await client.listTools();
  tools.tools.forEach((tool) => {
    console.log(`  - ${tool.name}: ${tool.description}`);
  });
 
  // Call the greet tool
  console.log("\nCalling greet tool:");
  const greetResult = await client.callTool({
    name: "greet",
    arguments: { name: "Developer" },
  });
  console.log("  Result:", greetResult.content[0].text);
 
  // Call the time tool
  console.log("\nCalling get_current_time tool:");
  const timeResult = await client.callTool({
    name: "get_current_time",
    arguments: {},
  });
  console.log("  Result:", timeResult.content[0].text);
 
  // Cleanup
  await client.close();
  serverProcess.kill();
}
 
testServer().catch(console.error);

# Add client script to package.json first
npm run build
npx tsx src/client.ts

# Build the project
npm run build
 
# Run the server
npm start
 
# Watch mode (requires tsx)
npx tsx --watch src/index.ts