# Topics

## Read Topic

`TOOL discourse_read_topic`

Read topic metadata and posts. Large post limits can require multiple upstream requests. For moderation queues, prefer reviewable list/detail evidence instead of fanning this tool out across flagged topics.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `post_limit` (argument, integer, optional) - Max posts to return (default 5, max 50)
  Type: integer
  
  Max posts to return (default 5, max 50)
  
  minimum: 1
  
  maximum: 50

- `start_post_number` (argument, integer, optional) - Start from this post number (1-based)
  Type: integer
  
  Start from this post number (1-based)
  
  minimum: 1

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_read_topic",
    "arguments": {
        "topic_id": 0,
        "post_limit": 1,
        "start_post_number": 1
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_read_topic",
  "arguments": {
    "topic_id": 0,
    "post_limit": 1,
    "start_post_number": 1
  }
});
```

### Python

```python
result = await session.call_tool("discourse_read_topic", arguments={
  "topic_id": 0,
  "post_limit": 1,
  "start_post_number": 1
})
```


## Read Post

`TOOL discourse_read_post`

Read a specific post. Returns JSON with id, topic_id, post_number, username, created_at, and raw content.

Authentication: no security requirement declared for this operation.

Parameters:

- `post_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_read_post",
    "arguments": {
        "post_id": 0
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_read_post",
  "arguments": {
    "post_id": 0
  }
});
```

### Python

```python
result = await session.call_tool("discourse_read_post", arguments={
  "post_id": 0
})
```


## Read Selected Topic Posts

`TOOL discourse_read_topic_posts`

Read exact, earliest, latest, around-post, or username-filtered topic evidence. Selection is bounded to 50 posts and reports the visible stream size without claiming the entire topic was loaded.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `selection_mode` (argument, string, required)
  Type: string
  
  enum: ["latest","earliest","post_ids","around_post","usernames"]

- `limit` (argument, integer, optional)
  Type: integer
  
  minimum: 1
  
  maximum: 50

- `post_ids` (argument, Array<integer>, optional)
  Type: Array<integer>
  
  minItems: 1
  
  maxItems: 50
  
  Items:
    Type: integer
    
    exclusiveMinimum: 0

- `post_number` (argument, integer, optional)
  Type: integer
  
  exclusiveMinimum: 0

- `usernames` (argument, Array<string>, optional)
  Type: Array<string>
  
  minItems: 1
  
  maxItems: 50
  
  Items:
    Type: string
    
    minLength: 1

- `replies_only` (argument, boolean, optional)
  Type: boolean

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_read_topic_posts",
    "arguments": {
        "topic_id": 0,
        "selection_mode": "latest",
        "limit": 1,
        "post_ids": [
          0
        ],
        "post_number": 0,
        "usernames": [
          "string"
        ],
        "replies_only": true
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_read_topic_posts",
  "arguments": {
    "topic_id": 0,
    "selection_mode": "latest",
    "limit": 1,
    "post_ids": [
      0
    ],
    "post_number": 0,
    "usernames": [
      "string"
    ],
    "replies_only": true
  }
});
```

### Python

```python
result = await session.call_tool("discourse_read_topic_posts", arguments={
  "topic_id": 0,
  "selection_mode": "latest",
  "limit": 1,
  "post_ids": [
    0
  ],
  "post_number": 0,
  "usernames": [
    "string"
  ],
  "replies_only": true
})
```


## Create Post

`TOOL discourse_create_post`

Create a post in a topic. author_username requires a global API key. Returns the actual upstream author so callers can verify attribution.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `raw` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 30000

- `author_username` (argument, string, optional)
  Type: string

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_post",
    "arguments": {
        "topic_id": 0,
        "raw": "string",
        "author_username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_create_post",
  "arguments": {
    "topic_id": 0,
    "raw": "string",
    "author_username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_create_post", arguments={
  "topic_id": 0,
  "raw": "string",
  "author_username": "string"
})
```


## Create Category

`TOOL discourse_create_category`

Create a new category. Returns JSON with id, slug, and name.

Authentication: no security requirement declared for this operation.

Parameters:

- `name` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 100

- `color` (argument, string, optional)
  Type: string
  
  pattern: "^[0-9a-fA-F]{6}$"

- `text_color` (argument, string, optional)
  Type: string
  
  pattern: "^[0-9a-fA-F]{6}$"

- `emoji` (argument, string, optional)
  Type: string

- `icon` (argument, string, optional)
  Type: string

- `parent_category_id` (argument, integer, optional)
  Type: integer
  
  exclusiveMinimum: 0

- `description` (argument, string, optional)
  Type: string
  
  minLength: 1
  
  maxLength: 10000

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_category",
    "arguments": {
        "name": "string",
        "color": "string",
        "text_color": "string",
        "emoji": "string",
        "icon": "string",
        "parent_category_id": 0,
        "description": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_create_category",
  "arguments": {
    "name": "string",
    "color": "string",
    "text_color": "string",
    "emoji": "string",
    "icon": "string",
    "parent_category_id": 0,
    "description": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_create_category", arguments={
  "name": "string",
  "color": "string",
  "text_color": "string",
  "emoji": "string",
  "icon": "string",
  "parent_category_id": 0,
  "description": "string"
})
```


## Create Topic

`TOOL discourse_create_topic`

Create a new topic. author_username requires a global API key. Returns the actual upstream author so callers can verify attribution.

Authentication: no security requirement declared for this operation.

Parameters:

- `title` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 300

- `raw` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 30000

- `category_id` (argument, integer, optional)
  Type: integer
  
  exclusiveMinimum: 0

- `tags` (argument, Array<string>, optional)
  Type: Array<string>
  
  maxItems: 10
  
  Items:
    Type: string
    
    minLength: 1
    
    maxLength: 100

- `author_username` (argument, string, optional)
  Type: string

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_topic",
    "arguments": {
        "title": "string",
        "raw": "string",
        "category_id": 0,
        "tags": [
          "string"
        ],
        "author_username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_create_topic",
  "arguments": {
    "title": "string",
    "raw": "string",
    "category_id": 0,
    "tags": [
      "string"
    ],
    "author_username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_create_topic", arguments={
  "title": "string",
  "raw": "string",
  "category_id": 0,
  "tags": [
    "string"
  ],
  "author_username": "string"
})
```


## Update Topic

`TOOL discourse_update_topic`

Update an existing topic (title, category, tags, featured_link). Returns JSON with updated topic details.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required) - Topic ID to update
  Type: integer
  
  Topic ID to update
  
  exclusiveMinimum: 0

- `title` (argument, string, optional) - New title
  Type: string
  
  New title
  
  minLength: 1
  
  maxLength: 300

- `category_id` (argument, integer, optional) - Move to category
  Type: integer
  
  Move to category
  
  exclusiveMinimum: 0

- `tags` (argument, Array<string>, optional) - Replace all tags
  Type: Array<string>
  
  Replace all tags
  
  maxItems: 10
  
  Items:
    Type: string
    
    minLength: 1
    
    maxLength: 100

- `featured_link` (argument, string, uri, optional) - Featured link URL
  Type: string, uri
  
  Featured link URL

- `original_title` (argument, string, optional) - For conflict detection - expected current title
  Type: string
  
  For conflict detection - expected current title

- `original_tags` (argument, Array<string>, optional) - For conflict detection - expected current tags
  Type: Array<string>
  
  For conflict detection - expected current tags
  
  Items:
    Type: string

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_topic",
    "arguments": {
        "topic_id": 0,
        "title": "string",
        "category_id": 0,
        "tags": [
          "string"
        ],
        "featured_link": "https://example.com",
        "original_title": "string",
        "original_tags": [
          "string"
        ]
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_update_topic",
  "arguments": {
    "topic_id": 0,
    "title": "string",
    "category_id": 0,
    "tags": [
      "string"
    ],
    "featured_link": "https://example.com",
    "original_title": "string",
    "original_tags": [
      "string"
    ]
  }
});
```

### Python

```python
result = await session.call_tool("discourse_update_topic", arguments={
  "topic_id": 0,
  "title": "string",
  "category_id": 0,
  "tags": [
    "string"
  ],
  "featured_link": "https://example.com",
  "original_title": "string",
  "original_tags": [
    "string"
  ]
})
```


## Update Post

`TOOL discourse_update_post`

Update the content of an existing post. Returns JSON with updated post details.

Authentication: no security requirement declared for this operation.

Parameters:

- `post_id` (argument, integer, required) - Post ID to update
  Type: integer
  
  Post ID to update
  
  exclusiveMinimum: 0

- `raw` (argument, string, required) - New post content (markdown)
  Type: string
  
  New post content (markdown)
  
  minLength: 1
  
  maxLength: 30000

- `edit_reason` (argument, string, optional) - Reason for the edit
  Type: string
  
  Reason for the edit
  
  maxLength: 500

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_post",
    "arguments": {
        "post_id": 0,
        "raw": "string",
        "edit_reason": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_update_post",
  "arguments": {
    "post_id": 0,
    "raw": "string",
    "edit_reason": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_update_post", arguments={
  "post_id": 0,
  "raw": "string",
  "edit_reason": "string"
})
```