ai-mcp-server

wafaa-rakchamber/ai-mcp-server

3.1

If you are the rightful owner of ai-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for project management with JWT authentication.

Tools
8
Resources
0
Prompts
0

Project Management MCP Server with JWT Authentication

A Model Context Protocol (MCP) server for project management that allows you to query information about users, projects, and tasks through an AI assistant. This server includes JWT token authentication for secure access.

🔐 Authentication

This MCP server uses JWT (JSON Web Tokens) for authentication. All tools (except generate_test_jwt) require a valid JWT token with appropriate permissions.

JWT Configuration

The server validates JWT tokens with the following requirements:

  • Algorithm: HS256
  • Issuer: project-management-system (configurable via JWT_ISSUER env var)
  • Audience: mcp-server (configurable via JWT_AUDIENCE env var)
  • Secret: Configurable via JWT_SECRET env var (default for testing only)

Required Permissions

  • read:projects: Required for project-related operations
  • read:users: Required for user-related operations
  • read:tasks: Required for task-related operations

Features

🔍 Available Tools

  1. generate_test_jwt - Generate a test JWT token for development (no auth required)

    • Input: User ID (user1, user2, user3, or user4)
    • Returns: Valid JWT token for testing

  2. get_project_workers - Find out who is working on a specific project

    • Permissions: read:projects, read:users
    • Input: Project name or ID
    • Returns: List of team members with their roles and tasks

  3. get_project_count - Get total number of projects and breakdown by status

    • Permissions: read:projects
    • Input: None
    • Returns: Total count and status breakdown (planning, active, on-hold, completed)

  4. get_user_workload - Get detailed information about a user's current work

    • Permissions: read:users, read:projects, read:tasks
    • Input: User name or ID
    • Returns: User's projects, tasks, and detailed information

  5. list_all_users - Get a list of all users in the system

    • Permissions: read:users
    • Input: None
    • Returns: All users with their roles and workload summary

  6. list_all_projects - Get a list of all projects in the system

    • Permissions: read:projects
    • Input: None
    • Returns: All projects with status and team size

  7. get_project_details - Get detailed information about a specific project

    • Permissions: read:projects, read:tasks
    • Input: Project name or ID
    • Returns: Complete project information including tasks and team members

  8. search_tasks_by_status - Search for tasks by their status

    • Permissions: read:tasks
    • Input: Status (todo, in-progress, review, done)
    • Returns: All tasks matching the status with details

📊 Sample Data

The server includes mock data with:

  • 4 Users: Alice (Project Manager), Bob (Developer), Carol (Designer), David (QA Engineer)
  • 4 Projects: E-commerce Platform, Mobile App Redesign, Data Analytics Dashboard, Legacy System Migration
  • 8 Tasks: Various tasks across different projects with different statuses and priorities

🚀 Setup and Installation

Prerequisites

  • Node.js 17 or higher
  • npm or yarn

Installation

  1. Clone or download this project
  2. Install dependencies:
npm install
  1. Build the project:
npm run build

Environment Variables

Configure the following environment variables:

# JWT Configuration (optional - defaults provided for development)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_ISSUER=project-management-system
JWT_AUDIENCE=mcp-server

# JWT Token for API access (set this to use the tools)
MCP_JWT_TOKEN=your-jwt-token-here

Getting Started with Authentication

  1. Generate a test JWT token:

    npm start
# Use the generate_test_jwt tool with a user ID (user1, user2, user3, or user4)

  2. Set the JWT token in your environment:

    # PowerShell
$env:MCP_JWT_TOKEN="your-generated-token"

    # Bash
export MCP_JWT_TOKEN="your-generated-token"

  3. Now you can use the protected tools

Running the Server

The server runs on stdio transport and is designed to be used with MCP-compatible clients.

npm start
# or
node build/index.js

🔧 Using with VS Code and GitHub Copilot

This project includes a .vscode/mcp.json configuration file for easy debugging with VS Code.

To use with GitHub Copilot in VS Code:

  1. Make sure the project is built (npm run build)
  2. The MCP server should be automatically available in VS Code
  3. You can debug the server using VS Code's debugging features

📖 Example Usage

Step 1: Generate a Test JWT Token

First, ask for a JWT token for one of the test users:

Query: "Generate a test JWT token for user1"

Response: You'll get a JWT token that you can use for authentication.

Step 2: Set the Token

Set the JWT token in your environment:

$env:MCP_JWT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Step 3: Use Protected Tools

Now you can ask authenticated questions like:

  • "Who is working on the E-commerce Platform project?"
  • "How many projects do we have here?"
  • "What is Alice working on right now?"
  • "Show me all users in the system"
  • "What are the details of the Mobile App Redesign project?"
  • "Find all tasks that are in progress"

Each response will include authentication information showing which user made the request.

🔒 Security Features

JWT Token Validation

  • Signature verification using HMAC SHA-256
  • Expiration time checking (24-hour default)
  • Issuer and audience validation
  • Permission-based access control

Permission System

Tools require specific permissions:

  • Project operations: read:projects
  • User operations: read:users
  • Task operations: read:tasks

Production Considerations

⚠️ Important for Production:

  • Change the JWT secret from the default value
  • Use environment variables for all configuration
  • Implement proper JWT token issuing via an authentication server
  • Add rate limiting and request validation
  • Use HTTPS for all communications
  • Implement proper logging and monitoring

🏗️ Architecture

The server is built using:

  • TypeScript for type safety
  • @modelcontextprotocol/sdk for MCP protocol implementation
  • Zod for runtime type validation
  • Node.js for the runtime environment

Data Structure

  • Users: Have roles, email, and are assigned to projects and tasks
  • Projects: Have status, team members, and associated tasks
  • Tasks: Have status, priority, assignee, and belong to projects

🛠️ Development

Project Structure

src/
├── index.ts          # Main server implementation
build/                # Compiled JavaScript output
.vscode/
├── mcp.json         # VS Code MCP configuration
package.json         # Project dependencies and scripts
tsconfig.json        # TypeScript configuration

Building

npm run build

Development Mode

npm run dev

🔒 Security

This is a demonstration server with mock data. In a production environment, you should:

  • Implement proper authentication and authorization
  • Connect to a real database instead of using mock data
  • Add input validation and sanitization
  • Implement rate limiting and other security measures

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

This is a demonstration project. Feel free to fork and modify for your own use cases.

🐛 Troubleshooting

Common Issues

  1. Server won't start: Make sure you've run npm run build first
  2. Dependencies missing: Run npm install
  3. TypeScript errors: Check your Node.js version (requires 17+)

Debug Mode

You can add logging by modifying the server code to use console.error() for debug output (never use console.log() as it interferes with the MCP protocol on stdio).

📚 Learn More