# 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)

```bash
npx github:Artemida1609/mcp-service
```

### Option 2: Install locally

```bash
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:**
```bash
export API_TOKEN="your-api-token-here"
export API_BASE_URL="https://api.yourplatform.com/v1"
```

**Windows (PowerShell):**
```powershell
$env:API_TOKEN="your-api-token-here"
$env:API_BASE_URL="https://api.yourplatform.com/v1"
```

**Windows (CMD):**
```cmd
set API_TOKEN=your-api-token-here
set API_BASE_URL=https://api.yourplatform.com/v1
```

### Running the Service

**Via npx:**
```bash
npx github:your-username/mcp-service
```

**Locally:**
```bash
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "username": "user@example.com",
  "password": "password123"
}
```

#### `refresh_token`
Refresh an expired access token.

**Parameters:**
- `refreshToken` (string, required): The refresh token

**Example:**
```json
{
  "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:

```javascript
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.