seatalk-mcp-server/README.md

A Model Context Protocol server for SeaTalk Open Platform integration

# SeaTalk MCP Server

This server provides [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-model-context-protocol) tools to interact with the SeaTalk API. It enables AI assistants to send and retrieve messages, access employee information, and interact with group chats via SeaTalk.

## Setup

1. Install dependencies:
   ```bash
   npm install
   ```

2. Create a `.env` file with your SeaTalk credentials:
   ```
   SEATALK_APP_ID=your_app_id
   SEATALK_APP_SECRET=your_app_secret
   ```

3. Build the server:
   ```bash
   npm run build
   ```

4. Start the server:
   ```bash
   npm start
   ```

## Installation

You can install this package via npm:

```bash
# Install globally
npm install -g seatalk-mcp-server

# Or use directly with npx (auto-install without prompts)
npx -y seatalk-mcp-server
```

## NPX Usage

This package can be used directly via `npx` without installing it globally. The `-y` flag automatically accepts installation prompts for seamless automation.

### Configuration in MCP Settings

Configure the SeaTalk server in your MCP settings by providing the required environment variables:

```json
{
  "mcpServers": {
    "seatalk-mcp-server": {
      "command": "npx",
      "args": ["-y", "seatalk-mcp-server"],
      "env": {
        "SEATALK_APP_ID": "your_app_id_here",
        "SEATALK_APP_SECRET": "your_app_secret_here"
      },
      "disabled": false
    }
  }
}
```

Required environment variables:
- `SEATALK_APP_ID`: Your SeaTalk application ID
- `SEATALK_APP_SECRET`: Your SeaTalk application secret

### Using with Cursor or other MCP-compatible tools

After configuring the server in your MCP settings, SeaTalk tools will be available for use in Cursor or other MCP-compatible environments.

## Local Development & Manual Build

If you prefer to clone the repository and build the server yourself, follow these steps:

### Prerequisites

- Node.js 16.0.0 or higher
- npm or yarn package manager

### Clone and Build

1. **Clone the repository:**
   ```bash
   git clone https://github.com/muhammad-iqbal/seatalk-mcp-server.git
   cd seatalk-mcp-server/seatalk-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Create environment configuration:**
   ```bash
   # Create .env file with your credentials
   echo "SEATALK_APP_ID=your_app_id_here" > .env
   echo "SEATALK_APP_SECRET=your_app_secret_here" >> .env
   ```

4. **Build the project:**
   ```bash
   npm run build
   ```

5. **Run the server directly:**
   ```bash
   node build/index.js
   ```

### Configuration in MCP Settings (Local Build)

When using the locally built version, configure your MCP settings to point to the built file:

```json
{
  "mcpServers": {
    "seatalk-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/seatalk-mcp-server/seatalk-server/build/index.js"],
      "env": {
        "SEATALK_APP_ID": "your_app_id_here",
        "SEATALK_APP_SECRET": "your_app_secret_here"
      },
      "disabled": false
    }
  }
}
```

**Note:** Replace `/path/to/your/seatalk-mcp-server/seatalk-server/build/index.js` with the actual absolute path to your built index.js file.

### Development Workflow

For active development, you can use the watch mode:

```bash
# Build and watch for changes
npm run watch

# In another terminal, run the server
node build/index.js
```

This approach is useful for:
- Contributing to the project
- Customizing the server for specific needs
- Testing unreleased features
- Running in environments where npx is not available

## Available Tools

### Employee Information

#### `get_employee_profile`
Get an employee's profile by employee code.

**Example:**
```json
{
  "employee_code": "EMP123"
}
```

**Response:**
```json
{
  "code": 0,
  "employee": {
    "employee_code": "EMP123",
    "name": "John Doe",
    "company_email": "john.doe@company.com",
    "department": {
      "department_code": "DEP001",
      "department_name": "Engineering"
    }
  }
}
```

#### `get_employee_code_with_email`
Get employee codes by email addresses.

**Example:**
```json
{
  "emails": ["john.doe@company.com", "jane.smith@company.com"]
}
```

**Response:**
```json
{
  "code": 0,
  "results": [
    {
      "email": "john.doe@company.com",
      "employee_code": "EMP123",
      "exists": true
    },
    {
      "email": "jane.smith@company.com",
      "employee_code": "EMP456",
      "exists": true
    }
  ]
}
```

#### `check_employee_existence`
Verify whether employees exist in the organization via SeaTalk ID.

**Example:**
```json
{
  "id": "ST12345"
}
```

**Response:**
```json
{
  "code": 0,
  "exists": true
}
```

#### `get_user_language_preference`
Get a user's language preference.

**Example:**
```json
{
  "employee_code": "EMP123"
}
```

**Response:**
```json
{
  "code": 0,
  "language": "en"
}
```

### Group Chat Management

#### `get_joined_group_chat_list`
Obtain group chats the bot joined.

**Example:**
```json
{
  "page_size": 10
}
```

**Response:**
```json
{
  "code": 0,
  "groups": [
    {
      "group_id": "group123",
      "group_name": "Engineering Team",
      "member_count": 15
    },
    {
      "group_id": "group456",
      "group_name": "Project Alpha",
      "member_count": 8
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_token_for_next_page"
}
```

#### `get_group_info`
Get information about a group chat, including member list.

**Example:**
```json
{
  "group_id": "group456"
}
```

**Response:**
```json
{
  "code": 0,
  "group_info": {
    "group_id": "group456",
    "group_name": "Project Alpha",
    "description": "Group for Project Alpha discussion",
    "created_at": 1615000000,
    "owner": {
      "employee_code": "EMP123",
      "name": "John Doe"
    }
  },
  "members": [
    {
      "employee_code": "EMP123",
      "name": "John Doe",
      "is_admin": true
    },
    {
      "employee_code": "EMP456",
      "name": "Jane Smith",
      "is_admin": false
    }
  ],
  "has_more": false
}
```

### Messaging

#### `get_thread_by_thread_id`
Retrieve all messages within a thread of a group chat.

**Example:**
```json
{
  "group_id": "group456",
  "thread_id": "thread123",
  "page_size": 20
}
```

**Response:**
```json
{
  "code": 0,
  "messages": [
    {
      "message_id": "msg001",
      "sender": {
        "employee_code": "EMP123",
        "name": "John Doe"
      },
      "tag": "text",
      "text": {
        "plain_text": "Hello team!"
      },
      "created_at": 1615456789
    }
  ],
  "has_more": false
}
```

#### `get_message_by_message_id`
Retrieve a message by its message ID.

**Example:**
```json
{
  "message_id": "msg001"
}
```

**Response:**
```json
{
  "code": 0,
  "message_id": "msg001",
  "sender": {
    "employee_code": "EMP123",
    "name": "John Doe"
  },
  "tag": "text",
  "text": {
    "plain_text": "Hello team!"
  },
  "created_at": 1615456789
}
```

#### `get_chat_history`
Obtain the group chat history (messages sent within 7 days).

**Example:**
```json
{
  "group_id": "group456",
  "page_size": 50
}
```

**Response:**
```json
{
  "code": 0,
  "messages": [
    {
      "message_id": "msg001",
      "sender": {
        "employee_code": "EMP123",
        "name": "John Doe"
      },
      "tag": "text",
      "text": {
        "plain_text": "Hello team!"
      },
      "created_at": 1615456789
    },
    {
      "message_id": "msg002",
      "sender": {
        "employee_code": "EMP456",
        "name": "Jane Smith"
      },
      "tag": "image",
      "image": {
        "content": "https://example.com/image.jpg"
      },
      "created_at": 1615456890
    }
  ],
  "has_more": true,
  "next_cursor": "next_page_cursor"
}
```

#### `send_message_to_group_chat`
Send a message to a group chat which the bot has been added to.

**Example (Text Message):**
```json
{
  "group_id": "group456",
  "message": {
    "tag": "text",
    "text": {
      "content": "Hello everyone! This is an announcement.",
      "format": 1
    }
  }
}
```

**Example (Image Message):**
```json
{
  "group_id": "group456",
  "message": {
    "tag": "image",
    "image": {
      "content": "base64_encoded_image_data"
    }
  }
}
```

**Response:**
```json
{
  "code": 0,
  "message_id": "msg123"
}
```

#### `send_message_to_bot_user`
Send a message to a user via the bot.

**Example (Text Message):**
```json
{
  "employee_code": "EMP123",
  "message": {
    "tag": "text",
    "text": {
      "content": "Hi there! Just checking in.",
      "format": 1
    }
  }
}
```

**Example (Interactive Message):**
```json
{
  "employee_code": "EMP123",
  "message": {
    "tag": "interactive_message",
    "interactive_message": {
      "elements": [
        {
          "tag": "header",
          "text": {
            "content": "Task Assignment",
            "tag": "plain_text"
          }
        },
        {
          "tag": "section",
          "text": {
            "content": "You have been assigned a new task.",
            "tag": "plain_text"
          }
        },
        {
          "tag": "action",
          "elements": [
            {
              "tag": "button",
              "text": {
                "content": "Accept",
                "tag": "plain_text"
              },
              "value": "accept_task"
            }
          ]
        }
      ]
    }
  }
}
```

**Response:**
```json
{
  "code": 0,
  "message_id": "msg125"
}
```

## Error Codes

All API responses include a `code` field that indicates the status of the request:

| Code | Description |
|------|-------------|
| 0 | Success |
| 2 | Server error |
| 5 | Resource not found |
| 8 | Server error |
| 100 | App access token is expired or invalid |
| 101 | API is rejected due to rate limit control |
| 102 | Request body contains invalid input |
| 103 | App permission denied |
| 104 | Bot capability is not turned on |
| 105 | App is not online |

### Auth-specific errors

| Code | Description |
|------|-------------|
| 1000 | App Secret is invalid |
| 2000 | Single Sign-On Token is expired or invalid |
| 2001 | User is not an employee of the current company |
| 2002 | Token belongs to another app |
| 2003 | Cursor invalid |
| 2004 | Cursor expired |

### User-specific errors

| Code | Description |
|------|-------------|
| 3000 | User not found with the current email |
| 3001 | User not found with the current code |
| 3002 | User is not a subscriber of the bot |
| 3003 | User is not signed in to SeaTalk |
| 3004 | Invalid custom field name |

### Message-specific errors

| Code | Description |
|------|-------------|
| 4000 | Message type is invalid |
| 4001 | Message exceeds the maximum length |
| 4002 | Message sending failed |
| 4003 | Message cannot be empty |
| 4004 | Fail to fetch the quoted message due to SeaTalk's internal error |
| 4005 | The quoted message cannot be found |
| 4009 | Message cannot be found via the message id provided |
| 4010 | The thread cannot be found |
| 4011 | Mention everyone (@all) is not allowed in thread replies |
| 4012 | No permission to update this message |

### App-specific errors

| Code | Description |
|------|-------------|
| 5000 | appID mismatch |
| 5001 | linkID expired |
| 5002 | App not released yet |
| 5003 | App link amount has reached the upper limit |

### Group chat errors

| Code | Description |
|------|-------------|
| 7000 | Group chat not found with the current code |
| 7001 | Bot is not a member of the group chat |

## License

MIT