hello-mcp-server

frankiewarren/hello-mcp-server

3.1

If you are the rightful owner of hello-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A simple TypeScript MCP server that demonstrates basic tool implementation with a friendly greeting service.

Tools
1
Resources
0
Prompts
0

Hello MCP Server - Learn MCP by Example

TypeScript Node.js MCP SDK License: MIT

The best way to learn Model Context Protocol (MCP) through hands-on exploration. This isn't just a working MCP server—it's an interactive tutorial that teaches you MCP concepts through extensively commented, real-world code.

🎓 Why This Repository Exists

Learning MCP can feel overwhelming with abstract concepts and scattered documentation. This repository takes a different approach:

  • Learn by Reading: Every line of code is extensively commented to explain both what it does and why
  • Learn by Testing: Use MCP Inspector to interact with real tools, resources, and prompts
  • Learn by Modifying: Start with working examples, then experiment and build your own features
  • Learn by Building: Understand the complete MCP server architecture from setup to deployment

Perfect for developers who learn best through practical examples rather than theoretical documentation.

📚 Learning Path: Start Here!

🚀 Step 1: Core MCP Understanding

Begin with src/index.ts - This is your learning goldmine! The file includes:

  • Clear explanations of what MCP is and why it matters
  • The three core MCP primitives: Tools, Resources, and Prompts
  • How Claude communicates with MCP servers
  • Working examples of each concept with detailed comments
  • Real request/response patterns you can test

Then read README.md (this file) for the big picture and practical usage.

🔧 Step 2: Project Configuration

Study TSCONFIG_EXPLAINED.md - Learn why each TypeScript setting matters for MCP development, explained in beginner-friendly terms.

Review package.json - Understand the essential MCP dependencies and build process.

🧪 Step 3: Hands-On Experimentation

  1. Set up and test (see Installation section below)
  2. Use MCP Inspector to interact with the server
  3. Modify the code - change greetings, add parameters, create new tools
  4. Build your own features using the patterns you've learned

💡 What You'll Learn

This repository demonstrates all essential MCP concepts:

Tools - Functions Claude Can Call

// Example: A greeting tool that accepts parameters and returns results
{
  name: "say_hello",
  description: "Says hello to the specified person",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", description: "The name to greet" }
    }
  }
}

Resources - Data Claude Can Read

// Example: Server information that updates in real-time
{
  uri: "mcp://server-info",
  name: "Server Information", 
  description: "Current server status and statistics"
}

Prompts - Templates That Guide Claude

// Example: Customizable greeting templates
{
  name: "greeting-generator",
  description: "Generate greetings based on tone and context",
  arguments: [
    { name: "tone", description: "formal, casual, friendly" },
    { name: "context", description: "meeting, email, introduction" }
  ]
}

🛠️ Installation & Setup

Prerequisites

  • Node.js 18.0 or later
  • npm or yarn package manager
  • Basic TypeScript knowledge (helpful but not required)

Quick Start

# Clone and setup
git clone https://github.com/YOUR_USERNAME/hello-mcp-server.git
cd hello-mcp-server
npm install

# Build the project
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Development Mode

# Auto-rebuild on changes
npm run dev

# Run the compiled server
npm start

🧪 Interactive Testing with MCP Inspector

MCP Inspector is your best friend for learning. It provides a web interface to test your server:

  1. Launch Inspector:

    npx @modelcontextprotocol/inspector node build/index.js

  2. Test Each Primitive:

    • Tools: Try the say_hello tool with different names
    • Resources: Read the server-info resource to see live data
    • Prompts: Use greeting-generator with various tones and contexts

  3. Watch the Communication: See the actual JSON-RPC messages between Claude and your server

📖 Detailed API Reference

Tools

say_hello

Demonstrates basic tool implementation with parameter validation and response formatting.

Input Schema:

{
  "name": "string"  // Required - The name of the person to greet
}

Example Usage:

{
  "name": "Alice"
}

Response:

{
  "content": [
    {
      "type": "text", 
      "text": "Hello, Alice! Welcome to my MCP server!"
    }
  ]
}

Resources

server-info (mcp://server-info)

Demonstrates dynamic resource generation with real-time data.

Response: Plain text with server statistics, uptime, system info, and capabilities.

Prompts

greeting-generator

Shows how to create flexible prompt templates with parameters.

Arguments:

  • tone (required): The tone of the greeting (formal, casual, friendly, etc.)
  • context (required): The context where the greeting will be used (meeting, email, etc.)

🎯 Learning Exercises

Beginner Exercises

  1. Modify the greeting: Change the say_hello response message
  2. Add a parameter: Add an optional language parameter to say_hello
  3. Create a simple tool: Build a get_time tool that returns the current time

Intermediate Exercises

  1. Add a new resource: Create a system-stats resource with memory and CPU info
  2. Build a calculation tool: Create a calculator tool with basic math operations
  3. Extend the prompt: Add more parameters to greeting-generator

Advanced Exercises

  1. File system integration: Create tools that can read/write files safely
  2. API integration: Build tools that call external APIs
  3. State management: Create tools that maintain state between calls

📁 Project Structure

hello-mcp-server/
├── src/
│   └── index.ts             # 🎓 Main learning resource - extensively commented MCP implementation
├── build/                   # ⚙️ Compiled JavaScript output
├── TSCONFIG_EXPLAINED.md    # 📚 TypeScript configuration tutorial  
├── GITHUB_SETUP.md          # 🚀 Publishing guide
├── CONTRIBUTING.md          # 🤝 Contribution guidelines
├── package.json             # 📦 Dependencies and scripts (with educational comments)
├── tsconfig.json            # ⚙️ TypeScript configuration
└── README.md                # 📖 This learning guide

🎓 Educational Philosophy

This project follows the principle that the best way to learn is through working examples:

  • Comments Explain Context: Not just what the code does, but why MCP works this way
  • Progressive Complexity: Start simple, then explore advanced patterns
  • Real-World Patterns: Learn practices you'll actually use in production
  • Interactive Learning: Test and modify rather than just read

🤝 Contributing to Learning

Help make this an even better learning resource:

  • Improve Comments: Make explanations clearer for beginners
  • Add Examples: Contribute new tools, resources, or prompts with educational value
  • Share Use Cases: Document how you've extended this for real projects
  • Fix Issues: Help other learners by improving error messages and documentation

See for guidelines.

🔮 Next Steps After Learning

Once you understand the patterns:

  1. Build Real Tools: Create MCP servers for your specific use cases
  2. Explore the Ecosystem: Check out other MCP servers and tools
  3. Join the Community: Share your creations and learn from others
  4. Contribute Back: Help improve MCP documentation and tooling

🌟 Success Stories

Have you used this repository to learn MCP? Share your story by opening an issue or discussion!

📞 Learning Support

📄 License

MIT License - See file for details.

🙏 Acknowledgments

  • Model Context Protocol team for creating an amazing standard
  • The TypeScript and Node.js communities for excellent tooling
  • Everyone who contributes to making MCP more accessible through education

Ready to learn MCP? Start with src/index.ts and let the commented code be your guide! 🚀