feat(wip): initial commits for sub-tasks 1,2,3 for task 23
This commit is contained in:
Ralph Khreish
170
mcp-server/README.md
Normal file
170
mcp-server/README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Task Master MCP Server
|
||||
|
||||
This module implements a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Task Master, allowing external applications to access Task Master functionality and context through a standardized API.
|
||||
|
||||
## Features
|
||||
|
||||
- MCP-compliant server implementation using FastMCP
|
||||
- RESTful API for context management
|
||||
- Authentication and authorization for secure access
|
||||
- Context storage and retrieval with metadata and tagging
|
||||
- Context windowing and truncation for handling size limits
|
||||
- Integration with Task Master for task management operations
|
||||
|
||||
## Installation
|
||||
|
||||
The MCP server is included with Task Master. Install Task Master globally to use the MCP server:
|
||||
|
||||
```bash
|
||||
npm install -g task-master-ai
|
||||
```
|
||||
|
||||
Or use it locally:
|
||||
|
||||
```bash
|
||||
npm install task-master-ai
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
The MCP server can be configured using environment variables or a `.env` file:
|
||||
|
||||
| Variable | Description | Default |
|
||||
| -------------------- | ---------------------------------------- | ----------------------------- |
|
||||
| `MCP_SERVER_PORT` | Port for the MCP server | 3000 |
|
||||
| `MCP_SERVER_HOST` | Host for the MCP server | localhost |
|
||||
| `MCP_CONTEXT_DIR` | Directory for context storage | ./mcp-server/contexts |
|
||||
| `MCP_API_KEYS_FILE` | File for API key storage | ./mcp-server/api-keys.json |
|
||||
| `MCP_JWT_SECRET` | Secret for JWT token generation | task-master-mcp-server-secret |
|
||||
| `MCP_JWT_EXPIRATION` | JWT token expiration time | 24h |
|
||||
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | info |
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Starting the Server
|
||||
|
||||
Start the MCP server as a standalone process:
|
||||
|
||||
```bash
|
||||
npx task-master-mcp-server
|
||||
```
|
||||
|
||||
Or start it programmatically:
|
||||
|
||||
```javascript
|
||||
import { TaskMasterMCPServer } from "task-master-ai/mcp-server";
|
||||
|
||||
const server = new TaskMasterMCPServer();
|
||||
await server.start({ port: 3000, host: "localhost" });
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
The MCP server uses API key authentication with JWT tokens for secure access. A default admin API key is generated on first startup and can be found in the `api-keys.json` file.
|
||||
|
||||
To get a JWT token:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/auth/token \
|
||||
-H "x-api-key: YOUR_API_KEY"
|
||||
```
|
||||
|
||||
Use the token for subsequent requests:
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/mcp/tools \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
### Creating a New API Key
|
||||
|
||||
Admin users can create new API keys:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/auth/api-keys \
|
||||
-H "Authorization: Bearer ADMIN_JWT_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"clientId": "user1", "role": "user"}'
|
||||
```
|
||||
|
||||
## Available MCP Endpoints
|
||||
|
||||
The MCP server implements the following MCP-compliant endpoints:
|
||||
|
||||
### Context Management
|
||||
|
||||
- `GET /mcp/context` - List all contexts
|
||||
- `POST /mcp/context` - Create a new context
|
||||
- `GET /mcp/context/{id}` - Get a specific context
|
||||
- `PUT /mcp/context/{id}` - Update a context
|
||||
- `DELETE /mcp/context/{id}` - Delete a context
|
||||
|
||||
### Models
|
||||
|
||||
- `GET /mcp/models` - List available models
|
||||
- `GET /mcp/models/{id}` - Get model details
|
||||
|
||||
### Execution
|
||||
|
||||
- `POST /mcp/execute` - Execute an operation with context
|
||||
|
||||
## Available MCP Tools
|
||||
|
||||
The MCP server provides the following tools:
|
||||
|
||||
### Context Tools
|
||||
|
||||
- `createContext` - Create a new context
|
||||
- `getContext` - Retrieve a context by ID
|
||||
- `updateContext` - Update an existing context
|
||||
- `deleteContext` - Delete a context
|
||||
- `listContexts` - List available contexts
|
||||
- `addTags` - Add tags to a context
|
||||
- `truncateContext` - Truncate a context to a maximum size
|
||||
|
||||
### Task Master Tools
|
||||
|
||||
- `listTasks` - List tasks from Task Master
|
||||
- `getTaskDetails` - Get detailed task information
|
||||
- `executeWithContext` - Execute operations using context
|
||||
|
||||
## Examples
|
||||
|
||||
### Creating a Context
|
||||
|
||||
```javascript
|
||||
// Using the MCP client
|
||||
const client = new MCPClient("http://localhost:3000");
|
||||
await client.authenticate("YOUR_API_KEY");
|
||||
|
||||
const context = await client.createContext("my-context", {
|
||||
title: "My Project",
|
||||
tasks: ["Implement feature X", "Fix bug Y"],
|
||||
});
|
||||
```
|
||||
|
||||
### Executing an Operation with Context
|
||||
|
||||
```javascript
|
||||
// Using the MCP client
|
||||
const result = await client.execute("generateTask", "my-context", {
|
||||
title: "New Task",
|
||||
description: "Create a new task based on context",
|
||||
});
|
||||
```
|
||||
|
||||
## Integration with Other Tools
|
||||
|
||||
The Task Master MCP server can be integrated with other MCP-compatible tools and clients:
|
||||
|
||||
- LLM applications that support the MCP protocol
|
||||
- Task management systems that support context-aware operations
|
||||
- Development environments with MCP integration
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
Reference in New Issue
Block a user