README.md•4.39 kB
# FastMCP Demo - TypeScript MCP Server
A demonstration project to understand the Model Context Protocol (MCP) using TypeScript. This project implements a basic MCP server with tools, resources, and prompts.
## What is MCP?
The Model Context Protocol (MCP) is a standardized protocol that enables AI assistants to securely access external data sources and tools. It provides a way for AI models to:
- **Tools**: Execute functions and operations
- **Resources**: Access data and information
- **Prompts**: Use predefined prompt templates
## Project Structure
```
fast-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript (generated)
├── package.json # Project dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
## Features
This demo server includes:
### Tools
- **hello**: A simple greeting tool that welcomes users
- **calculate**: Performs basic arithmetic operations (add, subtract, multiply, divide)
### Resources
- **demo://example**: A simple text resource
- **demo://config**: Server configuration in JSON format
### Prompts
- **greet_user**: Generates a greeting message for a user
- **explain_mcp**: Provides an explanation of what MCP is
## Setup
1. **Install dependencies:**
```bash
npm install
```
2. **Build the project:**
```bash
npm run build
```
3. **Run the server:**
```bash
npm start
```
Or use the development mode with auto-reload:
```bash
npm run dev
```
## How MCP Works
### Server Initialization
The server is created with capabilities for tools, resources, and prompts:
```typescript
const server = new Server(
{ name: "fast-mcp-demo", version: "0.1.0" },
{
capabilities: {
tools: {},
resources: {},
prompts: {},
},
}
);
```
### Transport
This server uses **stdio** (standard input/output) transport, which means it communicates via stdin/stdout. This is the most common transport for MCP servers.
### Request Handlers
Each capability requires request handlers:
- `ListToolsRequestSchema` - Lists available tools
- `CallToolRequestSchema` - Executes a tool
- `ListResourcesRequestSchema` - Lists available resources
- `ReadResourceRequestSchema` - Reads a resource
- `ListPromptsRequestSchema` - Lists available prompts
- `GetPromptRequestSchema` - Gets a prompt with arguments
## Testing with MCP Clients
To test this server, you'll need an MCP client. Popular options include:
1. **Claude Desktop** - Add the server to your MCP configuration
2. **MCP Inspector** - A debugging tool for MCP servers
3. **Custom MCP Client** - Build your own using the MCP SDK
### Example Configuration (Claude Desktop)
Add to your Claude Desktop MCP settings:
```json
{
"mcpServers": {
"fast-mcp-demo": {
"command": "node",
"args": ["/path/to/fast-mcp/dist/index.js"]
}
}
}
```
## Learning Path
This project was built incrementally to understand MCP concepts:
1. ✅ **Initial Setup** - TypeScript configuration and dependencies
2. ✅ **Basic Server** - Simple server with hello tool
3. ✅ **Resources** - Added resource reading capabilities
4. ✅ **Prompts** - Added prompt templates
5. ✅ **Advanced Tools** - Added calculate tool with error handling
## Key Concepts
### Tools
Tools are functions that the AI can call. They have:
- A name and description
- An input schema (JSON Schema)
- Execution logic that returns results
### Resources
Resources are data sources that can be read. They have:
- A URI identifier
- A name and description
- A MIME type
- Content that can be retrieved
### Prompts
Prompts are template messages that can be used to guide AI interactions. They have:
- A name and description
- Optional arguments
- Message templates
## Next Steps
To extend this demo, consider:
- Adding file system resources
- Implementing authentication
- Adding more complex tools (API calls, database queries)
- Using different transports (SSE, HTTP)
- Adding logging and error handling middleware
- Implementing caching for resources
## Resources
- [MCP Specification](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [FastMCP (Python)](https://gofastmcp.com/) - The Python equivalent
## License
MIT