Metadata-Version: 2.4
Name: appflowy-mcp
Version: 0.1.4
Summary: AppFlowy MCP server for workspace, space, page, database, and row operations
Project-URL: Homepage, https://github.com/weironz/appflowy_mcp
Project-URL: Repository, https://github.com/weironz/appflowy_mcp
Requires-Python: <3.15,>=3.14
Requires-Dist: fastmcp>=3.1.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-dotenv>=1.2.2
Description-Content-Type: text/markdown

# AppFlowy MCP

An MCP server for AppFlowy. This fork adds workspace folder, space, page, trash, favorite, and basic page-content tools on top of the original workspace/database/row tools.

## Requirements

- Python 3.14
- uv
- AppFlowy account credentials

## Configure In Codex

### Option 1: PyPI / uvx

Use this after the package is published to PyPI. This is the simplest setup for daily use.

Use `uvx` as the command:

```text
uvx
```

Use these arguments:

```text
appflowy-mcp
```

### Option 2: Local Source / uv

Use this when developing the MCP locally or running directly from a cloned repository.

Use `uv` as the command:

```text
uv
```

Use these arguments:

```text
run
--project
D:\codes\MCP\Appflowy-MCP
D:\codes\MCP\Appflowy-MCP\main.py
```

### Environment Variables

Set these environment variables:

```text
APPFLOWY_EMAIL=your-email@example.com
APPFLOWY_PASSWORD=your-password
```

With these variables set, tools automatically log in on first use. `appflowy_login` is still available when you want to provide credentials explicitly.

For self-hosted AppFlowy, also set the base URL:

```text
APPFLOWY_BASE_URL=http://localhost:8000
```

If omitted, `APPFLOWY_BASE_URL` defaults to `https://beta.appflowy.cloud`.

## AppFlowy Structure

Most write operations need both a workspace and a parent view:

```text
workspace -> space -> page/database
```

To create a page inside a space, pass the workspace ID and use the space `view_id` as `parent_view_id`.

## Tools

### Authentication

- `appflowy_login`
- `appflowy_refresh_token`

### Workspaces And Spaces

- `appflowy_list_workspaces`
- `appflowy_get_workspace_folder`
- `appflowy_list_spaces`
- `appflowy_create_space`
- `appflowy_update_space`

### Pages

- `appflowy_create_page`
- `appflowy_get_page`
- `appflowy_update_page`
- `appflowy_move_page_to_trash`
- `appflowy_restore_page_from_trash`
- `appflowy_delete_page_from_trash`
- `appflowy_favorite_page`
- `appflowy_list_trash`
- `appflowy_list_favorites`

### Page Content

- `appflowy_save_page`
- `appflowy_append_page_content`
- `appflowy_append_text_to_page`
- `appflowy_append_blocks_to_page`
- `appflowy_create_markdown_page`
- `appflowy_append_markdown_to_page`

Page-content support covers appending new document blocks, creating pages from Markdown, and appending Markdown to existing pages. AppFlowy exposes a high-level `append-block` endpoint, but not a matching high-level REST endpoint for deleting or editing arbitrary existing blocks. Page-level deletion through trash is supported.

When saving AI answers, notes, summaries, or generated content into AppFlowy, use `appflowy_save_page` by default. Its `content_format` field defaults to `markdown`, so agents do not need to ask users to say "save as Markdown" every time. Set `content_format` to `plain_text` only when the user explicitly wants the content preserved as literal plain text.

Use `appflowy_append_page_content` by default when adding AI-generated content to an existing page. It also treats content as Markdown unless `content_format` is set to `plain_text`.

Example paragraph block:

```json
{
  "type": "paragraph",
  "data": {
    "delta": [
      {
        "insert": "Hello from MCP"
      }
    ]
  }
}
```

Example Markdown page:

```json
{
  "parent_view_id": "space-or-page-view-id",
  "title": "Meeting Notes",
  "content": "# Meeting Notes\n\n- [ ] Follow up\n- **Important** decision\n\n```python\nprint(\"hello\")\n```",
  "content_format": "markdown"
}
```

Markdown conversion supports headings, paragraphs, dividers, bullet lists, numbered lists, todo lists, quotes, code blocks, image links, and inline bold, italic, strikethrough, code, and links.

### Databases And Rows

- `appflowy_list_databases`
- `appflowy_get_database_fields`
- `appflowy_list_rows`
- `appflowy_get_row_details`
- `appflowy_create_row`
- `appflowy_upsert_row`
- `appflowy_get_updated_rows`

## Local Run

```bash
uv run appflowy-mcp
```

## Publish To PyPI

Build and check the package:

```bash
uv build
uv publish --dry-run --trusted-publishing never
```

Publish with a PyPI API token:

```powershell
$env:UV_PUBLISH_TOKEN="pypi-your-token"
uv publish --trusted-publishing never
```

Do not commit PyPI tokens or write them into project files.

## Notes

- Tokens are stored in memory by the MCP server process.
- `APPFLOWY_EMAIL`, `APPFLOWY_PASSWORD`, and `APPFLOWY_BASE_URL` can also be provided through a local `.env` file.
- Some page and space endpoints are implemented from AppFlowy source routes that are not present in the public OpenAPI document.
