feishu-user-token-mcp-v2/README.md

A Model Context Protocol (MCP) server for Feishu user token management and authentication

# Feishu User Token MCP

A Model Context Protocol (MCP) server for Feishu user token management and authentication.

This MCP service is designed to manage Feishu user tokens, including obtaining the initial token through an OAuth 2.0 flow and subsequently refreshing it automatically.

## 🚀 Latest Updates

**v0.1.1** - Migrated from esbuild to Vite for better build performance and reliability:
- ✅ Improved build system with Vite
- ✅ Better handling of shebang lines and executable permissions
- ✅ Enhanced development experience with watch mode
- ✅ Resolved previous packaging issues

## Installation

### Using npx (Recommended)

```bash
npx feishu-user-token-mcp-v2
```

### Global Installation

```bash
npm install -g feishu-user-token-mcp-v2
feishu-user-token-mcp-v2
```

### Local Development

```bash
# Build the project (now using Vite)
npm run build

# Development mode with watch
npm run dev

# Run directly with node
node dist/index.js --help
```

### MCP Configuration

#### For Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "feishu-user-token-mcp": {
      "command": "npx",
      "args": ["feishu-user-token-mcp-v2"]
    }
  }
}
```

#### For Trae AI

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "feishu-user-token-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["feishu-user-token-mcp"]
    }
  }
}
```

## Architecture

The codebase is structured in a modular way to separate concerns:

-   `src/index.ts`: The main entry point of the MCP server.
-   `src/server.ts`: Defines the MCP server and its tools (`get_feishu_token`, `refresh_feishu_token`).
-   `src/handlers/authHandler.ts`: Contains the core logic for handling the authorization flow and token management.
-   `src/feishu/auth.ts`: Encapsulates the communication with the Feishu Open API for token exchange.
-   `src/utils/tokenStore.ts`: Manages reading and writing the `feishu_token.json` file.
-   `src/mcp/process.ts`: Handles starting and stopping the `feishu-mcp` process.

## How It Works

1.  **Configuration**: The service relies on a `mcp_config.json` file in the root directory to store the Feishu `app_id` and `app_secret`.

2.  **First-Time Use (`get_feishu_token`)**:
    -   When the `get_feishu_token` tool is called, it starts a temporary `express` server on `http://localhost:3000`.
    -   It constructs and opens the Feishu authorization URL.
    -   The user authorizes the application in their browser.
    -   Feishu redirects back to `http://localhost:3000/callback` with an authorization `code`.
    -   The server exchanges the `code` for an `access_token` and `refresh_token`.
    -   The new token is saved to `feishu_token.json`.
    -   It then attempts to stop any running `feishu-mcp` process and restart it with the new token.

3.  **Token Renewal (`refresh_feishu_token`)**:
    -   When the `refresh_feishu_token` tool is called, it reads the `refresh_token` from `feishu_token.json`.
    -   It makes a request to Feishu's API to get a new `access_token`.
    -   The new token is saved, and the `feishu-mcp` process is restarted.

## Configuration

1.  Create a `mcp_config.json` file in the root of this project:

    ```json
    {
        "app_id": "YOUR_FEISHU_APP_ID",
        "app_secret": "YOUR_FEISHU_APP_SECRET"
    }
    ```

2.  Replace `"YOUR_FEISHU_APP_ID"` and `"YOUR_FEISHU_APP_SECRET"` with your actual Feishu application credentials.

## Usage

### First Time: Getting the Initial Token

If you are running this for the first time or if `feishu_token.json` is missing, you need to authorize the application:

1.  Run the MCP service.
2.  Call the `get_feishu_token` tool with your `app_id` and `app_secret`.
3.  Your browser will open the Feishu authorization page. Log in and grant access.
4.  Once authorized, the local server will catch the redirect, obtain the token, and save it.

### Automatic Token Renewal

On subsequent runs, you can manually trigger a refresh by calling the `refresh_feishu_token` tool.

## Integration with Cursor

This MCP is designed to be called by a larger system like Cursor. The idea is that when Cursor detects that a Feishu API call fails due to an expired token, it would automatically invoke this MCP's `refresh_feishu_token` tool to get a new token and then retry the original API call. This creates a seamless experience where token expiry is handled automatically in the background.