Local Development MCP Server

A comprehensive, production-ready Model Context Protocol (MCP) server that provides AI assistants like Claude with tools for local development, task management, and document generation.

Perfect as a base project for building your own MCP servers!

🚀 Quick Start

Get up and running in 5 minutes:

# Install dependencies
npm install

# Build the project
npm run build

# Test it works
npm run dev

Then configure Claude Desktop to use it - see Quick Start Guide for details.

📚 Documentation

This project includes comprehensive documentation to help you understand, use, and extend the MCP server:

Document	Description	When to Read
QUICKSTART.md	Get started in 10 minutes	Start here! First time setup
DOCUMENTATION.md	Complete guide to MCP and this server	Learn the architecture and concepts
TUTORIAL.md	Build custom tools step-by-step	When adding your own tools
API_REFERENCE.md	Technical API documentation	Reference while coding
TROUBLESHOOTING.md	Common issues and solutions	When something doesn't work

✨ Features

File Operations

• read-file: Read contents of any file
• write-file: Write content to files, creating directories as needed
• list-directory: List directory contents with visual indicators

Task Management

• create-task: Create tasks with title, description, and priority
• list-tasks: View all tasks, filtered by status
• update-task-status: Update task status (todo/in-progress/done)

Document Generation

• generate-markdown-doc: Create structured markdown documents
• generate-readme: Generate professional README templates

🎯 What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude interact with external tools, data sources, and APIs in a standardized way. This project implements an MCP server that provides local development capabilities.

Learn more: MCP Documentation

🛠️ Technology Stack

• TypeScript - Type-safe server implementation
• MCP SDK - Official Model Context Protocol SDK
• Zod - Runtime type validation
• Node.js - Server runtime (18+ required)

📦 Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Basic TypeScript/JavaScript knowledge (for customization)

Setup

# Clone this repository
git clone <your-repo-url>
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

🔧 Configuration

Add this server to Claude Desktop by editing your configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "local-dev": {
      "command": "node",
      "args": [
        "C:\\Projects\\mcp-server\\dist\\index.js"
      ]
    }
  }
}

Important: Use the absolute path to your project's dist/index.js file.

Restart Claude Desktop completely for changes to take effect.

🧪 Testing

Verify the Connection

Open Claude Desktop and ask:

"What MCP servers are connected?"

You should see local-dev listed with all its tools.

Test a Tool

"Use local-dev to create a task titled 'Test Task' with description 'Testing my MCP server'"

Claude should create the task and confirm with a task ID.

📖 Usage Examples

File Operations

Read my package.json file
→ Claude uses read-file tool

List files in C:\Projects
→ Claude uses list-directory tool

Create a new file called notes.txt with content "Hello World"
→ Claude uses write-file tool

Task Management

Create a high priority task to implement authentication
→ Claude uses create-task tool

Show me all my tasks
→ Claude uses list-tasks tool

Mark task-1 as done
→ Claude uses update-task-status tool

Document Generation

Generate a README for a project called "Awesome Tool"
→ Claude uses generate-readme tool

Create a project proposal document with sections for Overview and Timeline
→ Claude uses generate-markdown-doc tool

🔨 Development

Available Scripts

npm run build   # Compile TypeScript to JavaScript
npm run dev     # Run in development mode with tsx
npm start       # Run the compiled server
npm run watch   # Watch for changes and rebuild

Project Structure

mcp-server/
├── src/
│   └── index.ts              # Main server implementation
├── dist/                     # Compiled JavaScript (generated)
├── node_modules/             # Dependencies
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript settings
├── README.md                 # This file
├── QUICKSTART.md            # Quick start guide
├── DOCUMENTATION.md         # Complete documentation
├── TUTORIAL.md              # Tool building tutorial
├── API_REFERENCE.md         # API reference
└── TROUBLESHOOTING.md       # Troubleshooting guide

🎓 Learning Path

New to MCP?

1. Read QUICKSTART.md - Get it working (10 min)
2. Read DOCUMENTATION.md - Understand how it works (30 min)
3. Try TUTORIAL.md - Build your first custom tool (20 min)

Building Custom Tools?

1. Review TUTORIAL.md - Step-by-step examples
2. Reference API_REFERENCE.md - Technical details
3. Check TROUBLESHOOTING.md - When stuck

🚀 Extending the Server

This server is designed to be a foundation for your own MCP servers. See TUTORIAL.md for detailed guides on:

• Creating simple text processing tools
• Adding input validation with Zod
• Building file system tools
• Integrating external APIs
• Managing stateful operations
• Handling async operations
• Best practices and patterns

Quick Example:

// Add to TOOLS array
{
  name: 'greet',
  description: 'Generate a personalized greeting',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name to greet' }
    },
    required: ['name']
  }
}

// Add handler
if (name === 'greet') {
  const { name: userName } = args as { name: string };
  return {
    content: [{
      type: 'text',
      text: `Hello, ${userName}! Welcome to MCP!`
    }]
  };
}

🐛 Troubleshooting

Having issues? Check TROUBLESHOOTING.md for solutions to common problems:

• Server not connecting to Claude
• Tool execution errors
• Build/compilation issues
• Performance problems
• File operation failures

📝 Best Practices

1. Always validate inputs - Use Zod for runtime type checking
2. Handle errors gracefully - Wrap operations in try-catch
3. Use async/await - Never block the event loop
4. Log to stderr - Never use console.log() in server code
5. Type your arguments - Use TypeScript types for safety
6. Document your tools - Clear descriptions help Claude use tools correctly

🤝 Contributing

This is a learning project and base template for MCP servers. Feel free to:

• Fork and customize for your needs
• Share improvements and extensions
• Report issues or suggestions
• Create pull requests

📄 License

MIT License - feel free to use this project as a foundation for your own MCP servers.

🔗 Resources

• MCP Specification: https://modelcontextprotocol.io
• MCP SDK: https://github.com/anthropics/anthropic-sdk-typescript
• Claude Documentation: https://docs.anthropic.com
• TypeScript: https://www.typescriptlang.org
• Zod: https://zod.dev

🎉 What's Next?

1. ✅ Complete the Quick Start
2. ✅ Read the Documentation to understand MCP
3. ✅ Follow the Tutorial to build custom tools
4. ✅ Use the API Reference while coding
5. ✅ Check Troubleshooting if you get stuck
6. ✅ Build something amazing!

💡 Example Use Cases

This server can be extended to:

• Development Tools: Code generation, refactoring, testing
• Project Management: Issue tracking, sprint planning, documentation
• Data Processing: File conversion, data analysis, report generation
• API Integration: Connect to GitHub, Jira, Slack, etc.
• Automation: Build scripts, deployment tools, monitoring
• Content Creation: Blog posts, documentation, marketing materials

🙏 Acknowledgments

Built with:

• Anthropic's Model Context Protocol
• The TypeScript and Node.js communities
• Developers exploring AI-powered development tools

---

Happy building! 🚀

For questions or issues, please check the documentation files or create an issue in this repository.