flarum-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# Flarum MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Flarum](https://flarum.org/) forums. This allows Claude Code and other MCP clients to interact with Flarum forums - creating, reading, updating, and deleting discussions, posts, users, and tags.
+
+## Installation
+
+```bash
+npm install -g flarum-mcp-server
+```
+
+## Configuration
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "flarum": {
+      "command": "flarum-mcp-server",
+      "env": {
+        "FLARUM_BASE_URL": "https://your-forum.com",
+        "FLARUM_USERNAME": "your-email@example.com",
+        "FLARUM_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FLARUM_BASE_URL` | Yes | Your Flarum forum URL |
+| `FLARUM_USERNAME` | No | Email or username for auto-login |
+| `FLARUM_PASSWORD` | No | Password for auto-login |
+
+## Available Tools
+
+### Discussions
+
+| Tool | Description |
+|------|-------------|
+| `flarum_list_discussions` | List discussions (supports filtering by user, tag, date) |
+| `flarum_get_discussion` | Get discussion details |
+| `flarum_create_discussion` | Create a new discussion |
+| `flarum_update_discussion` | Update a discussion |
+| `flarum_delete_discussion` | Delete/hide a discussion |
+
+### Posts
+
+| Tool | Description |
+|------|-------------|
+| `flarum_list_posts` | List posts in a discussion |
+| `flarum_get_post` | Get post details |
+| `flarum_create_post` | Create a reply |
+| `flarum_update_post` | Update a post |
+| `flarum_delete_post` | Delete/hide a post |
+
+### Users & Tags
+
+| Tool | Description |
+|------|-------------|
+| `flarum_list_users` | List users (supports search) |
+| `flarum_get_user` | Get user details |
+| `flarum_list_tags` | List all tags |
+
+### Authentication
+
+| Tool | Description |
+|------|-------------|
+| `flarum_login` | Login to the forum |
+| `flarum_logout` | Logout |
+| `flarum_check_auth` | Check authentication status |
+
+## Usage Examples
+
+In Claude Code, you can say:
+
+- "List the latest 10 discussions"
+- "Create a new discussion titled 'Hello World' with content 'This is my first post'"
+- "Reply to discussion 123 with 'Thanks for sharing!'"
+- "Show me all discussions by user john"
+- "Get discussions created after 2024-01-01"
+
+## Features
+
+- **Auto-login**: Configure credentials in environment variables for automatic authentication
+- **Token caching**: Tokens are cached locally (`~/.flarum-mcp-token.json`) with 5-year expiration
+- **Filtering**: Filter discussions by user, tag, and date range
+- **Soft delete**: Default delete operation hides content (recoverable), with option for permanent deletion
+
+## Requirements
+
+- Node.js >= 18.0.0
+- A Flarum forum with API access
+
+## Development
+
+```bash
+# Clone and install dependencies
+git clone https://github.com/wangxiaobo775/flarum-mcp-server.git
+cd flarum-mcp-server
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT

package/build/flarum-client.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Flarum API 客户端
+ * 封装所有与 Flarum 论坛的 HTTP 交互
+ */
+import type { LoginResult, Discussion, Post, Tag, User, ListParams, CreateDiscussionParams, UpdateDiscussionParams, CreatePostParams, UpdatePostParams } from "./types.js";
+export declare class FlarumClient {
+    private baseUrl;
+    private token;
+    private userId;
+    private cacheFilePath;
+    constructor(baseUrl?: string);
+    /**
+     * 从文件加载缓存的 Token
+     */
+    loadCachedToken(): boolean;
+    /**
+     * 保存 Token 到文件
+     */
+    private saveCachedToken;
+    /**
+     * 清除缓存的 Token
+     */
+    clearCachedToken(): void;
+    /**
+     * 验证当前 Token 是否有效
+     */
+    validateToken(): Promise<boolean>;
+    /**
+     * 设置认证 Token
+     */
+    setToken(token: string, userId?: string): void;
+    /**
+     * 获取当前 Token
+     */
+    getToken(): string | null;
+    /**
+     * 检查是否已登录
+     */
+    isAuthenticated(): boolean;
+    /**
+     * 构建请求头
+     */
+    private getHeaders;
+    /**
+     * 发送 HTTP 请求
+     */
+    private request;
+    /**
+     * 登录获取 Token
+     */
+    login(identification: string, password: string, remember?: boolean): Promise<LoginResult>;
+    /**
+     * 登出
+     */
+    logout(): void;
+    /**
+     * 获取讨论列表
+     */
+    getDiscussions(params?: ListParams): Promise<Discussion[]>;
+    /**
+     * 获取单个讨论
+     */
+    getDiscussion(id: string): Promise<Discussion>;
+    /**
+     * 创建讨论
+     */
+    createDiscussion(params: CreateDiscussionParams): Promise<Discussion>;
+    /**
+     * 更新讨论
+     */
+    updateDiscussion(id: string, params: UpdateDiscussionParams): Promise<Discussion>;
+    /**
+     * 删除讨论
+     * @param id 讨论 ID
+     * @param permanent 是否永久删除（默认 false，使用软删除/隐藏）
+     */
+    deleteDiscussion(id: string, permanent?: boolean): Promise<void>;
+    /**
+     * 获取讨论的帖子列表
+     */
+    getPosts(discussionId: string, params?: ListParams): Promise<Post[]>;
+    /**
+     * 获取单个帖子
+     */
+    getPost(id: string): Promise<Post>;
+    /**
+     * 创建帖子（回复）
+     */
+    createPost(params: CreatePostParams): Promise<Post>;
+    /**
+     * 更新帖子
+     */
+    updatePost(id: string, params: UpdatePostParams): Promise<Post>;
+    /**
+     * 删除帖子
+     * @param id 帖子 ID
+     * @param permanent 是否永久删除（默认 false，使用软删除/隐藏）
+     */
+    deletePost(id: string, permanent?: boolean): Promise<void>;
+    /**
+     * 获取所有标签
+     */
+    getTags(): Promise<Tag[]>;
+    /**
+     * 获取用户列表
+     */
+    getUsers(params?: ListParams): Promise<User[]>;
+    /**
+     * 获取单个用户
+     */
+    getUser(id: string): Promise<User>;
+    /**
+     * 解析讨论数据
+     */
+    private parseDiscussions;
+    /**
+     * 解析帖子数据
+     */
+    private parsePosts;
+    /**
+     * 解析标签数据
+     */
+    private parseTags;
+    /**
+     * 解析用户数据
+     */
+    private parseUsers;
+}
+export declare const flarumClient: FlarumClient;
+//# sourceMappingURL=flarum-client.d.ts.map

package/build/flarum-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flarum-client.d.ts","sourceRoot":"","sources":["../src/flarum-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,UAAU,EACV,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAOjB,MAAM,YAAY,CAAC;AAWpB,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,aAAa,CAAS;gBAElB,OAAO,CAAC,EAAE,MAAM;IAS5B;;OAEG;IACH,eAAe,IAAI,OAAO;IA8B1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAUxB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAcvC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAO9C;;OAEG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,eAAe,IAAI,OAAO;IAI1B;;OAEG;IACH,OAAO,CAAC,UAAU;IAalB;;OAEG;YACW,OAAO;IAsCrB;;OAEG;IACG,KAAK,CACT,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,WAAW,CAAC;IAkBvB;;OAEG;IACH,MAAM,IAAI,IAAI;IASd;;OAEG;IACG,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA8DhE;;OAEG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAapD;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+B3E;;OAEG;IACG,gBAAgB,CACpB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,UAAU,CAAC;IA+BtB;;;;OAIG;IACG,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB7E;;OAEG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAqB1E;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BzD;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBrE;;;;OAIG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBvE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAW/B;;OAEG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAwBpD;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAexC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA0ExB;;OAEG;IACH,OAAO,CAAC,UAAU;IAgDlB;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;OAEG;IACH,OAAO,CAAC,UAAU;CAanB;AAGD,eAAO,MAAM,YAAY,cAAqB,CAAC"}