MCP Platform Service

A minimal Model Context Protocol (MCP) service for integration with external platforms. This service provides CRUD operations, reference data fetching, and authentication capabilities.

Features

• ✅ CRUD operations (Create, Read, Update, Delete) for entities
• ✅ Reference data fetching (statuses, priorities, categories, etc.)
• ✅ Authentication via API token (environment variable) or login tool
• ✅ Token refresh support
• ✅ MCP-compatible server implementation
• ✅ Ready to run via npx from GitHub

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Installation

Option 1: Run via npx (from GitHub)

npx github:Artemida1609/mcp-service

Option 2: Install locally

git clone https://github.com/Artemida1609/mcp-service.git
cd mcp-service
npm install

Environment Variables

The service supports the following environment variables:

Variable	Description	Required	Default
API_TOKEN	API token for authentication	No*	-
API_BASE_URL	Base URL of the external platform API	No	https://api.example.com/v1
API_TIMEOUT	Request timeout in milliseconds	No	30000
ALLOW_LOGIN	Enable login tool (true/false)	No	true

* API_TOKEN is required unless you use the login tool to authenticate.

Usage

Setting Environment Variables

Linux/macOS:

export API_TOKEN="your-api-token-here"
export API_BASE_URL="https://api.yourplatform.com/v1"

Windows (PowerShell):

$env:API_TOKEN="your-api-token-here"
$env:API_BASE_URL="https://api.yourplatform.com/v1"

Windows (CMD):

set API_TOKEN=your-api-token-here
set API_BASE_URL=https://api.yourplatform.com/v1

Running the Service

Via npx:

npx github:your-username/mcp-service

Locally:

npm start
# or
node index.js

The service runs as an MCP server on stdio and communicates via the Model Context Protocol.

MCP Server Integration

Claude Desktop Configuration

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

macOS:

{
  "mcpServers": {
    "platform-service": {
      "command": "npx",
      "args": ["github:Artemida1609/mcp-service"],
      "env": {
        "API_TOKEN": "your-api-token-here",
        "API_BASE_URL": "https://api.yourplatform.com/v1"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "platform-service": {
      "command": "npx.cmd",
      "args": ["github:Artemida1609/mcp-service"],
      "env": {
        "API_TOKEN": "your-api-token-here",
        "API_BASE_URL": "https://api.yourplatform.com/v1"
      }
    }
  }
}

Other MCP Clients

The service communicates via stdio using the MCP protocol. Configure your MCP client to:

• Command: npx (or npx.cmd on Windows)
• Args: ["github:Artemida1609/mcp-service"]
• Environment variables as needed

Available Tools

CRUD Operations

get_entity

Retrieve a specific entity by ID and type.

Parameters:

• entityId (string, required): The unique identifier of the entity
• entityType (string, required): Type of entity (user, project, task, document)

Example:

{
  "entityId": "123",
  "entityType": "project"
}

create_entity

Create a new entity in the platform.

Parameters:

• entityType (string, required): Type of entity to create
• data (object, required): Entity data

Example:

{
  "entityType": "task",
  "data": {
    "title": "New Task",
    "description": "Task description",
    "status": "open"
  }
}

update_entity

Update an existing entity.

Parameters:

• entityId (string, required): The unique identifier
• entityType (string, required): Type of entity
• data (object, required): Fields to update

Example:

{
  "entityId": "123",
  "entityType": "task",
  "data": {
    "status": "completed"
  }
}

delete_entity

Delete an entity from the platform.

Parameters:

• entityId (string, required): The unique identifier
• entityType (string, required): Type of entity

Example:

{
  "entityId": "123",
  "entityType": "task"
}

Reference Data

get_reference

Fetch reference data (statuses, priorities, categories, etc.).

Parameters:

• referenceType (string, required): Type of reference (statuses, priorities, categories, tags, users)
• filters (object, optional): Optional filters

Example:

{
  "referenceType": "statuses",
  "filters": {
    "active": true
  }
}

Authentication

login

Authenticate with username and password. Stores the token for subsequent requests.

Parameters:

• username (string, required): Username
• password (string, required): Password

Example:

{
  "username": "user@example.com",
  "password": "password123"
}

refresh_token

Refresh an expired access token.

Parameters:

• refreshToken (string, required): The refresh token

Example:

{
  "refreshToken": "your-refresh-token-here"
}

API Endpoints

The service expects the external platform API to follow these conventions:

• GET /entities/{entityType}/{entityId} - Get entity
• POST /entities/{entityType} - Create entity
• PUT /entities/{entityType}/{entityId} - Update entity
• DELETE /entities/{entityType}/{entityId} - Delete entity
• GET /reference/{referenceType} - Get reference data
• POST /auth/login - Login
• POST /auth/refresh - Refresh token

All requests require Bearer token authentication in the Authorization header.

Project Structure

mcp-service/
├── index.js          # Main MCP server entry point
├── config.js         # Configuration and environment variables
├── auth.js           # Authentication token management
├── api-client.js     # HTTP client for API requests
├── handlers.js       # Tool handler implementations
├── tools.js          # Tool definitions and descriptions
├── schemas.js        # Input schemas for tools
├── package.json      # Dependencies and metadata
├── .gitignore        # Git ignore rules
└── README.md         # This file

Development

Local Development

1. Clone the repository
2. Install dependencies: npm install
3. Set environment variables
4. Run: npm start

Testing

To test the service manually, you can use an MCP client or test the handlers directly:

import { handleGetEntity } from './handlers.js';

const result = await handleGetEntity({
  entityId: '123',
  entityType: 'project'
});
console.log(result);

Troubleshooting

"No authentication token available" Error

• Ensure API_TOKEN is set in your environment, or
• Use the login tool to authenticate first

"Request timeout" Error

• Increase API_TIMEOUT environment variable
• Check network connectivity
• Verify API_BASE_URL is correct

Login Tool Disabled

• Set ALLOW_LOGIN=true in your environment variables

Module Not Found Errors

• Run npm install to install dependencies
• Ensure Node.js version is 18.0.0 or higher

Customization

To adapt this service for your specific platform:

1. Update API_BASE_URL to your platform's API endpoint
2. Modify endpoint paths in handlers.js if your API uses different routes
3. Adjust entity types in schemas.js to match your platform's entities
4. Update reference types in get_reference handler
5. Modify authentication flow in handleLogin if your platform uses different auth mechanisms

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.