TypeScript MCP Server

TypeScript MCP Server

A Model Context Protocol (MCP) server implementation using TypeScript and Express for payroll management.

What is MCP?

The Model Context Protocol (MCP) enables AI models to interact with external systems in a standardized way. It provides a framework for defining resources, tools, and prompts that LLMs can use to perform tasks.

For more information, visit the Model Context Protocol repository.

Features

• Implements the MCP protocol for LLM interactions
• Provides payroll management tools and employee information access
• Uses Express for HTTP handling
• Supports Server-Sent Events (SSE) for real-time communication
• Includes a client example for testing

Requirements

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository
2. Install dependencies:

npm install

3. Create a .env file based on the .env.example template:

cp .env.example .env

4. Update the .env file with your API configuration:

# API configuration
BASE_URL=http://app.localopfin.com
PORT=8089

Running the Server

Start the development server with:

npm run dev

For production:

npm run build
npm start

The server will run on port 8089 by default. You can change this by setting the PORT environment variable in the .env file.

Authentication

This server supports two authentication methods for API requests:

1. API authentication using authId and authKey
2. Partner authentication using partnerKey and clientKey

For custom authentication needs, you can modify the src/api.ts file.

API Endpoints

• GET /sse: Server-Sent Events endpoint for MCP communication
• POST /messages: Endpoint for clients to send messages to the MCP server

Available Resources

• greeting://welcome: A static welcome message
• users://{userId}: A dynamic resource that returns user data

Available Tools

• view-people: View information about a specific person using employee ID (requires authId and authKey authentication)
• view-all-people: View all people with optional filtering and pagination (supports both API authentication with authId/authKey or Partner authentication with partnerKey/clientKey)
• getEmployeeInfo: A simplified employee information retrieval tool that returns basic employee data (name, department, role) based on employee ID
• calculatePayroll: Calculate payroll for an employee based on hours worked and hourly rate (computes gross pay, 20% tax, and net pay)

Available Interfaces

The project includes typed interfaces for API responses:

• ApiResponse<T>: Generic API response wrapper with data, error, and status fields
• ApiConfig: Configuration for API client with baseUrl and optional headers
• ApiCredentials: For API-based authentication with authId and authKey
• PartnerCredentials: For partner-based authentication with partnerKey and clientKey

These interfaces help ensure type safety when working with API data.

Available Prompts

• ask-question: A prompt template for asking questions

Testing with the Example Client

The repository includes an example client that demonstrates how to connect to the MCP server and use its resources, tools, and prompts.

To run the example client (with the server already running):

npm run client

This will:

1. Connect to the MCP server
2. List available resources, tools, and prompts
3. Read the greeting resource
4. Use the available tools
5. Get the ask-question prompt

Usage with LLMs

This MCP server can be used with LLM clients that support the MCP protocol. Refer to the MCP documentation for information on how to connect LLM clients to this server.

License

MIT