使用说明

SeaTalk MCP Server

This server provides Model Context Protocol (MCP) 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

Install dependencies:
```
npm install
```

Create a .env file with your SeaTalk credentials:

SEATALK_APP_ID=your_app_id
SEATALK_APP_SECRET=your_app_secret

Build the server:
```
npm run build
```
Start the server:
```
npm start
```

Installation

You can install this package via npm:

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

{
  "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

Clone the repository:

git clone https://github.com/muhammad-iqbal/seatalk-mcp-server.git
cd seatalk-mcp-server/seatalk-server

Install dependencies:
```
npm install
```

Create environment configuration:

# Create .env file with your credentials
echo "SEATALK_APP_ID=your_app_id_here" > .env
echo "SEATALK_APP_SECRET=your_app_secret_here" >> .env

Build the project:
```
npm run build
```
Run the server directly:
```
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:

{
  "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:

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

{
  "employee_code": "EMP123"
}

Response:

{
  "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:

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

Response:

{
  "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:

{
  "id": "ST12345"
}

Response:

{
  "code": 0,
  "exists": true
}

`get_user_language_preference`

Get a user's language preference.

Example:

{
  "employee_code": "EMP123"
}

Response:

{
  "code": 0,
  "language": "en"
}

Group Chat Management

`get_joined_group_chat_list`

Obtain group chats the bot joined.

Example:

{
  "page_size": 10
}

Response:

{
  "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:

{
  "group_id": "group456"
}

Response:

{
  "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:

{
  "group_id": "group456",
  "thread_id": "thread123",
  "page_size": 20
}

Response:

{
  "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:

{
  "message_id": "msg001"
}

Response:

{
  "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:

{
  "group_id": "group456",
  "page_size": 50
}

Response:

{
  "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):

{
  "group_id": "group456",
  "message": {
    "tag": "text",
    "text": {
      "content": "Hello everyone! This is an announcement.",
      "format": 1
    }
  }
}

Example (Image Message):

{
  "group_id": "group456",
  "message": {
    "tag": "image",
    "image": {
      "content": "base64_encoded_image_data"
    }
  }
}

Response:

{
  "code": 0,
  "message_id": "msg123"
}

`send_message_to_bot_user`

Send a message to a user via the bot.

Example (Text Message):

{
  "employee_code": "EMP123",
  "message": {
    "tag": "text",
    "text": {
      "content": "Hi there! Just checking in.",
      "format": 1
    }
  }
}

Example (Interactive Message):

{
  "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:

{
  "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

使用说明

SeaTalk MCP Server

Setup

Installation

NPX Usage

Configuration in MCP Settings

Using with Cursor or other MCP-compatible tools

Local Development & Manual Build

Prerequisites

Clone and Build

Configuration in MCP Settings (Local Build)

Development Workflow

Available Tools

Employee Information

get_employee_profile

get_employee_code_with_email

check_employee_existence

get_user_language_preference

Group Chat Management

get_joined_group_chat_list

get_group_info

Messaging

get_thread_by_thread_id

get_message_by_message_id

get_chat_history

send_message_to_group_chat

send_message_to_bot_user

Error Codes

Auth-specific errors

User-specific errors

Message-specific errors

App-specific errors

Group chat errors

License

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器

`get_employee_profile`

`get_employee_code_with_email`

`check_employee_existence`

`get_user_language_preference`

`get_joined_group_chat_list`

`get_group_info`

`get_thread_by_thread_id`

`get_message_by_message_id`

`get_chat_history`

`send_message_to_group_chat`

`send_message_to_bot_user`