Hello MCP Server - Learn MCP by Example

Hello MCP Server - Learn MCP by Example

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 CONTRIBUTING.md 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

• Questions: GitHub Discussions
• Issues: GitHub Issues
• MCP Documentation: modelcontextprotocol.io
• Community: Join the MCP community for broader discussions

📄 License

MIT License - See LICENSE 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! 🚀