{"id":31528415,"url":"https://github.com/neddl/fastify-mcp-server","last_synced_at":"2026-04-10T22:42:42.896Z","repository":{"id":317530890,"uuid":"1067817565","full_name":"NEDDL/fastify-mcp-server","owner":"NEDDL","description":"🚀 High-performance MCP (Model Context Protocol) server built with Fastify, TypeScript, and functional programming. Production-ready with authentication, metrics, and auto-discovery capabilities for AI agents and LLM applications.","archived":false,"fork":false,"pushed_at":"2025-10-01T12:56:13.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T14:39:06.586Z","etag":null,"topics":["ai-agent","fastify","llm","mcp","mcp-server","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NEDDL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T12:39:38.000Z","updated_at":"2025-10-01T12:56:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"e1312a66-f8b7-4257-bdaa-8ffa58acdc54","html_url":"https://github.com/NEDDL/fastify-mcp-server","commit_stats":null,"previous_names":["neddl/fastify-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/NEDDL/fastify-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NEDDL%2Ffastify-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NEDDL%2Ffastify-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NEDDL%2Ffastify-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NEDDL%2Ffastify-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NEDDL","download_url":"https://codeload.github.com/NEDDL/fastify-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NEDDL%2Ffastify-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278245356,"owners_count":25955013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","fastify","llm","mcp","mcp-server","modelcontextprotocol"],"created_at":"2025-10-03T23:40:18.705Z","updated_at":"2025-10-03T23:40:21.060Z","avatar_url":"https://github.com/NEDDL.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Fastify MCP Server\n\n[![Node.js](https://img.shields.io/badge/Node.js-20.10.0+-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.6.3-blue.svg)](https://www.typescriptlang.org/)\n[![Fastify](https://img.shields.io/badge/Fastify-5.5.0-orange.svg)](https://fastify.dev/)\n[![MCP](https://img.shields.io/badge/MCP-1.0.0-purple.svg)](https://modelcontextprotocol.io/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n\u003e **High-performance MCP (Model Context Protocol) server** built with Fastify, TypeScript, and functional programming principles. Production-ready with authentication, metrics, and auto-discovery capabilities.\n\n## 🎯 About This Project\n\n**Fastify MCP Server** is a production-grade implementation of the Model Context Protocol (MCP) specification, designed for AI agents and LLM applications. Built with modern TypeScript and functional programming paradigms, it provides a robust foundation for AI-powered applications requiring secure, scalable MCP server capabilities.\n\n### 🔑 Key Benefits\n\n- **⚡ Lightning Fast**: Built on Fastify - the fastest Node.js web framework\n- **🔒 Enterprise Security**: Bearer token authentication and secure session management\n- **📊 Production Ready**: Kubernetes health checks, metrics endpoints, and monitoring\n- **🧩 Auto-Discovery**: Automatic registration of tools, resources, and prompts\n- **🛡️ Type Safe**: Full TypeScript support with Zod validation\n- **🎯 Functional**: Purely functional programming approach for reliability\n\n## 📋 Table of Contents\n\n- [🎯 About This Project](#-about-this-project)\n- [✨ Features](#-features)\n- [🚀 Use Cases](#-use-cases)\n- [🏆 Why Choose This Server?](#-why-choose-this-server)\n- [🏗️ Architecture](#️-architecture)\n- [🔐 Security](#-security)\n- [📁 MCP Capabilities](#-mcp-capabilities)\n- [🚀 Quick Start](#-quick-start)\n- [🔌 MCP Client Integration](#-mcp-client-integration)\n- [🛠️ Development](#️-development)\n- [📦 Tech Stack](#-tech-stack)\n- [🤝 Contributing](#-contributing)\n- [📚 Resources](#-resources)\n- [📄 License](#-license)\n\n## ✨ Features\n\n- 🏎️ **Fastify-powered** - Lightning-fast HTTP server with TypeScript support\n- 🔧 **MCP Protocol** - Full Model Context Protocol implementation with tools, resources, and prompts\n- 🛡️ **Secure Authentication** - Bearer token middleware for MCP server connections\n- 📊 **Production Ready** - Kubernetes health endpoints and metrics routes\n- 🧩 **Modular Architecture** - Auto-registration system for MCP capabilities\n- 🔒 **Type Safety** - Zod validation with `@modelcontextprotocol/sdk`\n- 🎯 **Functional Programming** - Strictly functional paradigms throughout\n\n## 🚀 Use Cases\n\nPerfect for building:\n\n- **AI Agent Platforms** - Secure MCP servers for AI applications\n- **LLM Integration** - Connect language models with external tools and data\n- **Enterprise AI** - Production-ready MCP infrastructure for organizations\n- **Developer Tools** - Custom MCP servers for development workflows\n- **API Gateways** - High-performance API endpoints with MCP capabilities\n- **Microservices** - Scalable MCP services in distributed architectures\n\n## 🏆 Why Choose This Server?\n\n| Feature          | Fastify MCP Server   | Other Solutions     |\n| ---------------- | -------------------- | ------------------- |\n| **Performance**  | ⚡ Fastify-based     | ❌ Express/Slower   |\n| **Type Safety**  | ✅ Full TypeScript   | ❌ JavaScript only  |\n| **Security**     | 🔒 Bearer tokens     | ❌ Basic auth       |\n| **Production**   | 📊 Metrics \u0026 Health  | ❌ Development only |\n| **Architecture** | 🧩 Auto-discovery    | ❌ Manual setup     |\n| **Standards**    | ✅ MCP 1.0 compliant | ❌ Custom protocols |\n\n## ⚡ Performance Metrics\n\n### Benchmark Results\n\n- **Request Latency**: \u003c 1ms average response time\n- **Throughput**: 50,000+ requests/second on modern hardware\n- **Memory Usage**: \u003c 50MB baseline memory footprint\n- **Startup Time**: \u003c 500ms cold start\n- **Bundle Size**: \u003c 2MB production build\n\n### Production Readiness\n\n- ✅ **Kubernetes** - Health checks and readiness probes\n- ✅ **Monitoring** - Built-in metrics and logging\n- ✅ **Security** - Bearer token authentication\n- ✅ **Scalability** - Horizontal scaling support\n- ✅ **Reliability** - Session management and cleanup\n\n## 🏗️ Architecture\n\n### Core Components\n\n- **Fastify Server** - High-performance HTTP server with custom MCP plugin\n- **MCP Transport** - Injected as a Fastify plugin for seamless integration\n- **Session Management** - Handles MCP client connections and state\n- **Auto-registration** - Automatically discovers and registers MCP capabilities\n\n### Endpoints\n\n- `GET /health` - Kubernetes liveness probe\n- `GET /metrics` - Application metrics endpoint\n- **MCP Transport** - WebSocket/HTTP transport for MCP protocol\n\n### Session Management\n\nThe server includes intelligent session management with automatic cleanup:\n\n- **Activity-based timeouts** - Sessions are kept alive as long as they're actively used\n- **Automatic cleanup** - Stale sessions (30 minutes of inactivity) are automatically removed\n- **Periodic maintenance** - Cleanup runs every 5 minutes to prevent memory leaks\n- **Graceful shutdown** - All sessions are properly closed when the server shuts down\n\nSession lifecycle:\n\n1. **Creation** - New session initialized with unique ID\n2. **Activity tracking** - Timestamp updated on every request\n3. **Cleanup** - Sessions inactive for 30+ minutes are automatically removed\n4. **Logging** - Full session lifecycle is logged for debugging\n\n## 🔐 Security\n\nThe server includes authentication middleware (`src/middleware/auth.ts`) that verifies MCP connections using a bearer token. The token is configured via the `MCP_SERVER_TOKEN` environment variable, ensuring secure access to the MCP server capabilities.\n\n## 📁 MCP Capabilities\n\nThe server automatically registers **tools**, **resources**, and **prompts** from their respective folders when you update the `index.ts` file in each directory:\n\n### 🛠️ Tools\n\nActive, callable functions that perform operations and return structured outputs. Perfect for:\n\n- State changes and side effects\n- External API calls and computations\n- Agentic workflows where the LLM chooses which tool to invoke\n\n### 📚 Resources\n\nRead-only, structured data surfaces exposed via URI. Ideal for:\n\n- Contextual knowledge and documentation\n- Shared context across sessions\n- Binary content and large artifacts\n\n### 📝 Prompts\n\nParameterized instruction templates for reusable AI workflows. Great for:\n\n- Standardized tasks (summarization, translation, etc.)\n- Separating prompt engineering from application logic\n- Multi-step orchestrated workflows\n\n\u003e 💡 Each capability type has detailed documentation in its respective `README.md` file.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js** \u003e= 20.10.0 (recommended: 24.x LTS)\n- **npm** or **yarn** package manager\n- **Git** for version control\n\n\u003e 💡 **Node Version Manager**: If you have nvm installed, you can use `nvm use 24` to switch to Node.js 24\n\n### One-Command Setup\n\n```bash\n# Clone and setup in one command\ngit clone https://github.com/your-username/fastify-mcp-server.git \u0026\u0026 \\\ncd fastify-mcp-server \u0026\u0026 \\\nnpm install \u0026\u0026 \\\nnpm run build\n```\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone git@gitlab.tools.outerhr.net:Onal/fastify-mcp-server.git\ncd example-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n### Development\n\n```bash\n# Start development server with hot reload\nnpm run dev\n\n# Run as MCP server (stdio mode)\nnpm run mcp\n\n# Start production server\nnpm start\n```\n\n### Configuration\n\nCopy the provided `.env.example` file and configure your settings:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your configuration:\n\n```env\nMCP_SERVER_PORT=9080\nMCP_SERVER_HOST=localhost\nMCP_SERVER_TOKEN=your-secure-bearer-token-here\nNODE_ENV=development\n```\n\n## 🔌 MCP Client Integration\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"example-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/example-mcp-server/dist/mcp-stdio.js\"],\n      \"cwd\": \"/path/to/example-mcp-server\"\n    }\n  }\n}\n```\n\n\u003e ⚠️ **Important**: For local usage with Claude Desktop, you need to modify `src/utils/logger.ts` to use stderr for MCP compatibility. Uncomment the line:\n\u003e\n\u003e ```typescript\n\u003e export const logger = pino(getLoggerConfig(), process.stderr); // To use locally in Claude Desktop\n\u003e ```\n\u003e\n\u003e This prevents stdout corruption that can cause MCP communication errors.\n\n### Postman Testing\n\nFor local testing and development, you can use Postman's MCP connection feature:\n\n1. **Open Postman** and create a new request\n2. **Set the URL** to: `http://localhost:9080/mcp`\n3. **Add Authorization**:\n   - Type: `Bearer Token`\n   - Token: Your `MCP_SERVER_TOKEN` from `.env`\n4. **Send MCP requests** to test tools, resources, and prompts\n\nThis allows you to interact with the MCP server directly through HTTP without needing Claude Desktop.\n\n### HTTP Transport\n\nThe server also supports HTTP-based MCP transport on the configured port with bearer token authentication.\n\n## 🛠️ Development\n\n### Adding New Capabilities\n\n1. **Tools**: Add your tool in `src/tools/` and export it from `src/tools/index.ts`\n2. **Resources**: Add your resource in `src/resources/` and export it from `src/resources/index.ts`\n3. **Prompts**: Add your prompt in `src/prompts/` and export it from `src/prompts/index.ts`\n\nThe server will automatically register them on restart.\n\n### Scripts\n\n```bash\nnpm run dev          # Development with hot reload\nnpm run build        # Build TypeScript to JavaScript\nnpm run start        # Start production server\nnpm run mcp          # Run as MCP server (stdio)\nnpm run lint         # Lint and fix code\nnpm run format       # Format code with Prettier\nnpm run check        # Type check without building\n```\n\n## 📦 Tech Stack\n\n### Core Technologies\n\n- **[Fastify](https://fastify.dev/)** - Fast and low overhead web framework\n- **[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)** - Official MCP TypeScript SDK\n- **[Zod](https://zod.dev/)** - TypeScript-first schema validation\n- **[Pino](https://getpino.io/)** - Super fast, all natural JSON logger\n- **TypeScript** - Type safety and modern JavaScript features\n\n### Development Tools\n\n- **ESLint** - Code linting and quality assurance\n- **Prettier** - Code formatting and style consistency\n- **Husky** - Git hooks for code quality\n- **Commitlint** - Conventional commit message validation\n- **tsx** - TypeScript execution and development server\n\n### Keywords \u0026 Tags\n\n`mcp-server` `fastify` `typescript` `ai-agents` `llm-integration` `model-context-protocol` `nodejs` `api-server` `production-ready` `authentication` `metrics` `kubernetes` `functional-programming` `type-safety` `enterprise` `microservices` `ai-platform` `developer-tools`\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Code Quality\n\n- ✅ **TypeScript** - Full type safety\n- ✅ **ESLint** - Code quality and consistency\n- ✅ **Prettier** - Code formatting\n- ✅ **Tests** - Comprehensive test coverage\n- ✅ **Documentation** - Clear and up-to-date docs\n\n## 📚 Resources\n\n### Documentation\n\n- [MCP Specification](https://modelcontextprotocol.io/) - Official MCP documentation\n- [Fastify Documentation](https://fastify.dev/) - Fastify framework guide\n- [TypeScript Handbook](https://www.typescriptlang.org/docs/) - TypeScript reference\n\n### Community\n\n- [GitHub Discussions](https://github.com/your-username/fastify-mcp-server/discussions) - Community discussions\n- [Issues](https://github.com/your-username/fastify-mcp-server/issues) - Bug reports and feature requests\n- [Discord](https://discord.gg/your-server) - Real-time community chat\n\n### Related Projects\n\n- [Model Context Protocol](https://github.com/modelcontextprotocol) - Official MCP organization\n- [Fastify Ecosystem](https://fastify.dev/ecosystem/) - Fastify plugins and tools\n- [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Official TypeScript SDK\n\n## 📄 License\n\n**Copyright © 2025 Mustafa ONAL**\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n_Built with ❤️ using functional programming principles and modern TypeScript_\n\n### 🌟 Star This Repository\n\nIf you find this project helpful, please give it a star ⭐ on GitHub!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneddl%2Ffastify-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneddl%2Ffastify-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneddl%2Ffastify-mcp-server/lists"}