npm package: @fui-org/fui-mcp
Description: MCP server for FUI low-code system - manage projects and modules via AI
Author: minhphongvn
Latest version: 1.0.2

# FUI MCP Server

MCP server for FUI low-code system - manage projects and modules via AI.

## Quick Start

No installation required! You can run this MCP server directly using `npx`:

```bash
npx @fui-org/fui-mcp
```

## Configuration

### 1. Claude Desktop
Add this to your `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fui-mcp": {
      "command": "npx",
      "args": ["-y", "@fui-org/fui-mcp"],
      "env": {
        "FUI_API_TOKEN": "YOUR_FUI_API_KEY_HERE"
      }
    }
  }
}
```

### 2. Cursor
Go to **Cursor Settings** > **Features** > **MCP Servers** > **Add New**:

- **Name**: `fui-mcp`
- **Type**: `command`
- **Command**: `npx -y @fui-org/fui-mcp`
- **Environment Variables**:
  - `FUI_API_TOKEN` = `your_token_from_fui.vn`

### 3. Chrome Extension Integration
To use this MCP server from a Chrome Extension, run it in SSE mode:

```bash
npx @fui-org/fui-mcp --sse
# Server listening on http://localhost:3001
```

Or specify a custom port:
```bash
npx @fui-org/fui-mcp --sse --port 8080
```

In your Extension (background script):
```javascript
const eventSource = new EventSource('http://localhost:3001/sse');
eventSource.onmessage = (event) => {
  console.log('MCP Message:', JSON.parse(event.data));
};
// Use POST /messages to send requests
```

### Prerequisites
- [Node.js](https://nodejs.org/) (v18 or higher)
- FUI API Token (Get it from [fui.vn](https://fui.vn/))
- `FUI_API_BASE` pointing to your FUI API base URL
- Include a bundled `src/skills/` folder in this MCP package if you want every checkout to copy the full skill set into project workspaces

## Local Staging Workspace

This MCP now supports a local staging workflow for patch-based editing.

- Default workspace root: `~/.fui-mcp/workspaces`
- Override with env: `FUI_MCP_WORKDIR=/your/custom/path`

Checked-out modules are materialized as:

```text
<workspaceRoot>/<projectId>/
|-- skills/
|   `-- fui-skill/
|       |-- SKILL.md
|       `-- ...
`-- <moduleId>/
    |-- _info.json
    |-- module.json
    |-- script.js
    |-- header.html
    |-- body.html
    |-- dependencies.json
    `-- components/
        |-- _components.json
        `-- *.vue
```

On every `checkout_module`, MCP will also copy the bundled `src/skills/` folder into `<workspaceRoot>/<projectId>/skills`.
If the bundled folder is missing, MCP writes a fallback `skills/fui-skill/SKILL.md` there so the agent still has project-local guidance.

Recommended flow:

1. Optionally call `resolve_target` with `/projectId/moduleId`
2. Call `checkout_module`
   - either with `target: "/projectId/moduleId"`
   - or with `projectId` + `moduleId`
3. `checkout_module` automatically sets the active module target
4. Read the copied project skills in `<workspaceRoot>/<projectId>/skills/` before editing
5. Optionally call `get_fui_skill_rules` or read `lowcode://skill/fui` for a concise MCP-provided summary
6. Optionally call `sync_staged_module` to refresh from remote
   - `moduleDir` can be omitted when an active target exists
7. Let the agent edit local files with patches
8. Review/apply changes
9. Call `preview_publish` and ask the user whether they want to push to FUI
10. Call `publish_staged_module`
   - `moduleDir` can be omitted when an active target exists
   - `approvalToken` from `preview_publish` is required



## Tools

| Tool | Description |
|------|-------------|
| `resolve_target` | Resolve `/project/module` into concrete FUI IDs |
| `get_fui_skill_rules` | Read the critical FUI skill rules before editing |
| `get_active_module` | Show the current active staged module target |
| `set_active_module` | Set the active staged module target explicitly |
| `clear_active_module` | Clear the current active staged module target |
| `list_projects` | List available FUI projects |
| `list_modules` | List modules inside a project |
| `create_module` | Create a new module (HTML page) in a project |
| `get_module` | Get module content (HTML, CSS, Vue components) |
| `checkout_module` | Fetch a module into the local staging workspace by `target` or explicit IDs |
| `sync_staged_module` | Refresh a staged local module from remote, optionally using the active target |
| `preview_publish` | Preview staged local changes, create a publish approval token, and prompt the agent to ask the user before pushing |
| `publish_staged_module` | Publish a staged local module directory back to FUI using the approval token from `preview_publish` |

## Resources

| URI | Description |
|-----|-------------|
| `lowcode://modules/{projectId}/{moduleId}` | Read module content |
| `lowcode://skill/fui` | Read the concise FUI skill rules |
| `lowcode://skill/fui/raw` | Read the raw bundled FUI skill document when the package includes `skills/fui-skill/` |

## Prompts

| Prompt | Description |
|--------|-------------|
| `generate-vue-component` | Generate Vue 2 component template |