# ragflow-mcp-server-fixed

[中文说明](./README.zh-CN.md)

A fixed RAGFlow MCP server for stdio MCP clients.

It keeps the executable name `ragflow-mcp-server`, so clients can switch from
the original package by changing only the package source.

## What This Fixes

Some RAGFlow deployments return errors from the legacy chat endpoint, for
example:

```text
'NoneType' object is not subscriptable
required argument are missing: messages
```

This server handles that by:

- calling RAGFlow HTTP APIs directly;
- parsing stream responses defensively;
- falling back to the OpenAI-compatible RAGFlow endpoint when needed;
- returning clearer error messages from RAGFlow.

## Tools

| Tool | Purpose |
| --- | --- |
| `list_datasets` | List RAGFlow datasets. |
| `create_chat` | Create a chat assistant and session for a dataset. |
| `chat` | Ask a question in a session returned by `create_chat`. |
| `ask_configured_chat` | Ask a server-configured RAGFlow chat assistant directly. |
| `retrieve` | Retrieve matching chunks directly from a dataset. |

For most usage, configure `--default-chat-name` or `--default-chat-id`, then use
`ask_configured_chat`.

## Quick Start

```json
{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/FoundZiGu/ragflow-mcp-server-fixed.git@v0.1.2",
    "ragflow-mcp-server",
    "--api-key",
    "ragflow-REPLACE_WITH_YOUR_KEY",
    "--base-url",
    "http://<RAGFLOW_HOST>:9380",
    "--default-chat-name",
    "<CHAT_NAME>"
  ]
}
```

If your MCP client supports environment variables:

```json
{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/FoundZiGu/ragflow-mcp-server-fixed.git@v0.1.2",
    "ragflow-mcp-server"
  ],
  "env": {
    "RAGFLOW_API_KEY": "ragflow-REPLACE_WITH_YOUR_KEY",
    "RAGFLOW_BASE_URL": "http://<RAGFLOW_HOST>:9380",
    "RAGFLOW_DEFAULT_CHAT_NAME": "<CHAT_NAME>"
  }
}
```

Use chat ID instead of name when possible:

```json
{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/FoundZiGu/ragflow-mcp-server-fixed.git@v0.1.2",
    "ragflow-mcp-server",
    "--api-key",
    "ragflow-REPLACE_WITH_YOUR_KEY",
    "--base-url",
    "http://<RAGFLOW_HOST>:9380",
    "--default-chat-id",
    "<CHAT_ID>"
  ]
}
```

## Server Options

| Option | Environment variable | Description |
| --- | --- | --- |
| `--api-key` | `RAGFLOW_API_KEY` | RAGFlow API key. |
| `--base-url` | `RAGFLOW_BASE_URL` | RAGFlow base URL. |
| `--default-chat-id` | `RAGFLOW_DEFAULT_CHAT_ID` | Existing RAGFlow chat assistant ID for `ask_configured_chat`. |
| `--default-chat-name` | `RAGFLOW_DEFAULT_CHAT_NAME` | Existing RAGFlow chat assistant name for `ask_configured_chat`. |
| `--default-session-name` | `RAGFLOW_DEFAULT_SESSION_NAME` | Session name created for the configured chat. |

## Local Development

```bash
uv run ragflow-mcp-server --help
```

```bash
export RAGFLOW_API_KEY="ragflow-REPLACE_WITH_YOUR_KEY"
export RAGFLOW_BASE_URL="http://<RAGFLOW_HOST>:9380"
export RAGFLOW_DEFAULT_CHAT_NAME="<CHAT_NAME>"
uv run python tests/smoke_test.py
```

## Security

- Do not commit API keys.
- Prefer environment variables for secrets.
- Rotate keys that have appeared in logs, screenshots, public issues, or chat
  transcripts.