Metadata-Version: 2.3
Name: mcp-tm
Version: 0.2.1
Summary: Add your description here
Author: Livid Su
Author-email: Livid Su <qq1532250087@gmail.com>
Requires-Dist: mcp[cli]
Requires-Dist: pandas
Requires-Dist: sqlalchemy
Requires-Dist: python-dotenv
Requires-Dist: pymysql
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# MySQL + Feishu MCP Tool

This package provides a Model Context Protocol (MCP) server with:
- Read-only MySQL query capability.
- Feishu remote MCP connection capability.

## Features

- **Read-only Access**: Only allows `SELECT` and `SHOW` statements for SQL safety.
- **MySQL SSL Support**: Supports SSL connections for cloud databases.
- **Feishu Remote MCP**: Supports `initialize`, `tools/list`, and `tools/call` against Feishu MCP endpoint.
- **Feishu Sheets Read/Write**: Supports reading and writing Feishu Sheets via Open API.
- **Feishu Bitable Read/Write**: Supports reading and batch writing Feishu Bitable with optional table clear.
- **Env-based Config**: Uses `.env` for all credentials and endpoint settings.

## Installation

1.  Clone this repository.
2.  Install dependencies:
    ```bash
    uv sync
    ```

## Configuration

1.  Copy `.env.example` to `.env`:
    ```bash
    cp .env.example .env
    ```
2.  Edit `.env` with your MySQL and Feishu credentials:

    ```ini
    MYSQL_HOST=localhost
    MYSQL_PORT=3306
    MYSQL_USER=your_username
    MYSQL_PASSWORD=your_password
    MYSQL_DATABASE=your_database
    
    # Optional: MySQL SSL
    MYSQL_USE_SSL=false
    MYSQL_SSL_CA=/path/to/ca-cert.pem

    # Feishu MCP
    FEISHU_MCP_URL=https://mcp.feishu.cn/mcp
    FEISHU_OPEN_API_URL=https://open.feishu.cn/open-apis
    FEISHU_MCP_APP_ID=cli_xxx
    FEISHU_MCP_APP_SECRET=xxx
    FEISHU_MCP_ALLOWED_TOOLS=search-doc,fetch-doc,create-doc,update-doc
    ```
`FEISHU_MCP_APP_ID` and `FEISHU_MCP_APP_SECRET` are used to request tenant access token dynamically before each Feishu MCP call.

## Usage

Run the MCP server:

```bash
mcp-tm
```

## Tools

### `read_sql`

Executes a SQL query and returns the results as JSON.

-   **Arguments**:
    -   `query_sql` (string): The SQL query to execute (e.g., "SELECT * FROM users LIMIT 10").
-   **Returns**:
    -   JSON string of the query results.

### `feishu_list_tools`

Lists available Feishu MCP tools under the configured credentials and allowed tool set.

-   **Arguments**:
    -   `allowed_tools` (string, optional): Comma-separated tool names for this call only.
-   **Returns**:
    -   JSON-RPC response string from Feishu MCP.

### `feishu_call_tool`

Calls a specific Feishu MCP tool.

-   **Arguments**:
    -   `tool_name` (string): Tool name to call, for example `fetch-doc`.
    -   `arguments_json` (string): JSON object string for tool arguments.
    -   `allowed_tools` (string, optional): Comma-separated tool names for this call only.
-   **Returns**:
    -   JSON-RPC response string from Feishu MCP.

### `feishu_read_sheet`

Reads data from a Feishu Sheet range.

-   **Arguments**:
    -   `spreadsheet_token` (string): Spreadsheet token in URL.
    -   `sheet_id` (string): Sheet ID in URL.
    -   `range_ref` (string, optional): Range part for API path. Empty means reading by `sheet_id`.
-   **Returns**:
    -   Open API JSON response string.

### `feishu_write_sheet`

Writes data to a Feishu Sheet.

-   **Arguments**:
    -   `spreadsheet_token` (string): Spreadsheet token in URL.
    -   `sheet_id` (string): Sheet ID in URL.
    -   `values_json` (string): JSON string of either 2D array or object array.
    -   `start_cell` (string, optional): Start cell like `A1`.
    -   `clear_sheet` (bool, optional): Clear existing used range before write.
-   **Returns**:
    -   JSON string with write result and write range.

### `feishu_read_bitable`

Reads records from a Feishu Bitable table.

-   **Arguments**:
    -   `app_token` (string): Bitable app token.
    -   `table_id` (string): Bitable table ID.
    -   `page_size` (int, optional): Page size (max 500).
-   **Returns**:
    -   JSON string containing all fetched records.

### `feishu_write_bitable`

Batch writes records into a Feishu Bitable table.

-   **Arguments**:
    -   `app_token` (string): Bitable app token.
    -   `table_id` (string): Bitable table ID.
    -   `records_json` (string): JSON object array. Keys should match field names.
    -   `clear_table` (bool, optional): Delete existing records before write.
-   **Returns**:
    -   JSON string with summary including written records and ignored fields.
