MCP Assistant Server
A production-ready Model Context Protocol (MCP) server that provides tools and resources for AI assistants. This server is fully configured for deployment on Render and includes comprehensive examples of tools, resources, and best practices.
🚀 Features
Tools
- Weather Tool: Get current weather information for any city
- Calculator: Perform mathematical calculations
- Web Search: Search the web for information
- Date/Time: Get current date and time in various formats
- Text Processing: Process and analyze text with multiple operations
Resources
- System Information: Real-time system statistics
- Server Configuration: Current server settings
- Help Guide: Built-in documentation
Production Ready
- TypeScript with strict type checking
- Comprehensive error handling
- Winston logging
- Docker support
- Health checks
- Environment-based configuration
- Rate limiting ready
📋 Prerequisites
- Node.js 18+
- npm or yarn
- Git
🛠️ Installation
- Clone the repository:```bash
cd mcp-server
2. Install dependencies:```bash
npm install
- Create environment file:```bash
cp .env.example .env
4. Build the project:```bash
npm run build
🏃♂️ Running Locally
Development Mode```bash
npm run dev
### Production Mode```bash
npm run build
npm start
With Docker```bash
Build the image
docker build -t mcp-assistant-server .
Run the container
docker run -p 3000:3000 mcp-assistant-server
## 🚀 Deployment on Render
### Quick Deploy
1. Push your code to GitHub
2. Connect your GitHub repository to Render
3. Render will automatically detect the `render.yaml` configuration
4. Click "Deploy"
### Manual Setup
1. Create a new Web Service on Render
2. Connect your GitHub repository
3. Configure:
- Build Command: `npm install && npm run build`
- Start Command: `npm start`
- Environment: Node
- Add environment variables from `.env.example`
### Environment Variables
Set these in Render's dashboard:
- `NODE_ENV=production`
- `PORT=3000`
- `LOG_LEVEL=info`
- Add any API keys as needed
## 📦 Project Structure```
mcp-server/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── server.ts # HTTP server for health checks
│ ├── tools/ # Tool implementations
│ │ ├── index.ts
│ │ ├── weather.ts
│ │ ├── calculator.ts
│ │ ├── search.ts
│ │ ├── date.ts
│ │ └── text-processing.ts
│ ├── resources/ # Resource handlers
│ │ ├── index.ts
│ │ ├── system-info.ts
│ │ ├── config.ts
│ │ └── help.ts
│ └── utils/
│ └── logger.ts # Winston logger configuration
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── render.yaml # Render deployment config
├── Dockerfile
└── .env.example
🔧 Available Scripts
npm run build- Build TypeScript to JavaScriptnpm start- Start production servernpm run dev- Start development server with hot reloadnpm run lint- Run ESLintnpm run format- Format code with Prettiernpm run typecheck- Type check without buildingnpm test- Run testsnpm run clean- Clean build directory
📡 API Endpoints
Health Check```
GET /health
Returns server health status
### Server Info```
GET /info
Returns server capabilities and version
🔌 MCP Protocol
This server implements the Model Context Protocol (MCP) which allows AI assistants to:
- Call Tools: Execute functions with parameters
- Read Resources: Access system information and configuration
- Handle Requests: Process tool and resource requests via stdio
Example Tool Call```json
{
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"city": "New York",
"units": "fahrenheit"
}
}
}
### Example Resource Read```json
{
"method": "resources/read",
"params": {
"uri": "system://info"
}
}
🔒 Security
- Environment variables for sensitive data
- Input validation on all tools
- Safe expression evaluation in calculator
- Non-root Docker user
- Rate limiting ready
- Comprehensive error handling
🐛 Troubleshooting
Build Errors```bash
Clean and rebuild
npm run clean
npm install
npm run build
### Port Already in Use```bash
# Change port in .env
PORT=3001
Docker Issues```bash
Rebuild without cache
docker build --no-cache -t mcp-assistant-server .
```
📈 Monitoring
The server includes:
- Health endpoint for uptime monitoring
- Winston logging with different levels
- Error tracking
- Performance metrics in system info
🤝 Contributing
- Fork the repository
- Create your feature branch
- Run tests and linting
- Commit your changes
- Push to the branch
- Open a Pull Request
📄 License
MIT License - feel free to use this in your projects!
🆘 Support
For issues or questions:
- Check the built-in help resource:
help://guide - Open an issue on GitHub
- Review the logs in production
🎯 Next Steps
After deployment:
- Test the health endpoint:
https://your-app.onrender.com/health - Configure any API keys needed for enhanced features
- Monitor logs in Render dashboard
- Scale as needed based on usage
Ready to Deploy! This MCP server is fully configured and ready for production use on Render. Simply push to GitHub and deploy! 🚀
