Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions .github/workflows/publish_docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
name: Publish Docs

# Builds docs.discourse.org from openapi.json and the MCP snapshot, and publishes it to GitHub
# Pages, each time main changes (the Update Docs pull requests included).
on:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: false

jobs:
publish:
runs-on: ubuntu-latest
timeout-minutes: 10
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v7

- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm

- run: npm ci

- run: npx sourcey build -o dist

# Every file the site serves today keeps its address: openapi.json and openapi.yml, the
# Bruno and Postman collections, the schemas, the logo the document names and the rest.
# The reference above replaces only index.html.
- name: Keep the repository's files at their addresses
run: git ls-files -z | grep -zv -e '^\.github/' -e '^index\.html$' | xargs -0 cp --parents -n -t dist/

- uses: actions/upload-pages-artifact@v5
with:
path: dist

- id: deployment
uses: actions/deploy-pages@v5
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
node_modules/
dist/
32 changes: 30 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,36 @@ which will load the json file directly instead of live converting the yml file
to json. Now browse to http://localhost:3001 and verify your changes still look
okay.

Then you can commit your changes and create a PR. This is because we are using
github pages to host the static doc website.
Then you can commit your changes and create a PR. Once it merges, the Publish
Docs workflow builds docs.discourse.org from openapi.json and publishes it to
GitHub Pages.

### The published site

docs.discourse.org is built with [sourcey](https://github.com/sourcey/sourcey)
from openapi.json and the tools of the Discourse MCP server. To see it as it
will be published:

```
npm install
npm run docs
```

`sourcey.config.ts` sets it up. `discourse.overlay.yaml` groups the API's
sections under three headings, and `discourse.anchors.json` keeps every link
into the previous page (`#tag/Posts/operation/createTopicPostPM` and the rest)
landing on its endpoint.

The MCP Reference is a snapshot of the tools, resources and prompts the server
lists (`discourse.mcp.json`), in the toolsets it declares
(`discourse-mcp.groups.json`). Refresh it after a release of `@discourse/mcp`:

```
npm run mcp:snapshot
```

Anything new the snapshot brings is listed after the toolsets until
`discourse-mcp.groups.json` names its section, and the build says which.

### Automatic openapi.yml generation

Expand Down
211 changes: 211 additions & 0 deletions discourse-mcp.groups.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
{
"On by default": {
"Site": [
"discourse_select_site",
"site_categories",
"site_tags",
"site_groups"
],
"Search": [
"discourse_search",
"discourse_filter_topics",
"discourse_search_posts"
],
"Topics": [
"discourse_read_topic",
"discourse_read_post",
"discourse_read_topic_posts",
"discourse_create_post",
"discourse_create_category",
"discourse_create_topic",
"discourse_update_topic",
"discourse_update_post"
],
"Users": [
"discourse_get_user",
"discourse_list_user_posts",
"discourse_list_users",
"discourse_create_user",
"discourse_update_user"
],
"Chat": [
"discourse_get_chat_messages",
"chat_channels",
"user_chat_channels"
],
"Drafts": [
"discourse_get_draft",
"discourse_save_draft",
"discourse_delete_draft",
"user_drafts"
],
"Uploads": [
"discourse_upload_file"
],
"Data Explorer": [
"discourse_get_query",
"discourse_run_query",
"discourse_create_query",
"discourse_update_query",
"discourse_delete_query",
"explorer_schema",
"explorer_queries",
"explorer_schema_tables",
"explorer_queries_page",
"sql_query"
],
"Private messages": [
"discourse_list_private_messages",
"discourse_read_private_message",
"discourse_create_private_message",
"discourse_reply_private_message",
"discourse_invite_to_private_message"
]
},
"Community (opt-in)": {
"Activity": [
"discourse_get_post_replies",
"discourse_list_latest_posts",
"discourse_get_topic_view_stats",
"discourse_get_user_summary",
"discourse_list_user_actions",
"discourse_list_directory_items"
],
"Groups": [
"discourse_list_groups",
"discourse_get_group",
"discourse_list_group_posts",
"discourse_list_group_members",
"discourse_list_group_membership_requests",
"discourse_create_group",
"discourse_update_group",
"discourse_delete_group",
"discourse_add_group_members_by_username",
"discourse_add_group_members_by_user_id",
"discourse_add_group_members_by_email",
"discourse_invite_group_members_by_email",
"discourse_remove_group_members_by_username",
"discourse_remove_group_members_by_user_id",
"discourse_remove_group_members_by_email",
"discourse_add_group_owners_by_username",
"discourse_add_group_owners_by_user_id",
"discourse_add_group_owners_by_email",
"discourse_remove_group_owners_by_username",
"discourse_remove_group_owners_by_user_id",
"discourse_remove_group_owners_by_email",
"discourse_handle_group_membership_request",
"discourse_request_group_membership",
"discourse_join_group",
"discourse_leave_group"
],
"Tag groups": [
"discourse_search_tag_groups",
"discourse_list_tag_groups",
"discourse_get_tag_group",
"discourse_create_tag_group",
"discourse_update_tag_group",
"discourse_delete_tag_group"
],
"Moderation": [
"discourse_get_review_queue_count",
"discourse_list_reviewables",
"discourse_list_reviewable_topics",
"discourse_get_reviewable",
"discourse_get_user_moderation_summary",
"discourse_get_post_revision",
"discourse_perform_reviewable_action"
]
},
"AI (opt-in)": {
"AI agents": [
"discourse_ai_list_agents",
"discourse_ai_get_agent",
"discourse_ai_create_agent",
"discourse_ai_update_agent",
"discourse_ai_delete_agent",
"discourse_ai_create_agent_user",
"discourse_ai_export_agent",
"discourse_ai_import_agent"
],
"AI custom tools": [
"discourse_ai_get_custom_tool_guide",
"discourse_ai_list_custom_tools",
"discourse_ai_get_custom_tool",
"discourse_ai_create_custom_tool",
"discourse_ai_update_custom_tool",
"discourse_ai_delete_custom_tool",
"discourse_ai_test_custom_tool",
"discourse_ai_export_custom_tool",
"discourse_ai_import_custom_tool",
"ai_custom_tools_authoring_guide"
],
"AI features": [
"discourse_ai_list_features",
"discourse_ai_get_feature_config",
"discourse_ai_update_feature_config"
],
"AI insights": [
"discourse_ai_get_topic_summary",
"discourse_ai_semantic_search",
"discourse_ai_list_sentiment_posts"
]
},
"Administration (opt-in)": {
"Administration": [
"discourse_list_categories",
"discourse_list_site_settings",
"discourse_manage_user_activation"
],
"Site settings": [
"discourse_update_site_setting"
],
"Webhooks": [
"discourse_list_webhooks",
"discourse_get_webhook",
"discourse_create_webhook",
"discourse_update_webhook",
"discourse_delete_webhook",
"discourse_list_webhook_events",
"discourse_ping_webhook",
"discourse_redeliver_webhook_event"
],
"Themes": [
"discourse_list_themes",
"discourse_get_theme",
"discourse_create_theme",
"discourse_install_theme",
"discourse_update_theme",
"discourse_update_theme_fields",
"discourse_update_theme_setting",
"discourse_update_theme_translations",
"discourse_sync_remote_theme",
"discourse_upload_theme_asset",
"discourse_delete_theme"
],
"Analytics": [
"discourse_list_reports",
"discourse_get_report",
"discourse_get_support_dashboard"
],
"Workflows": [
"discourse_list_workflows",
"discourse_get_workflow",
"discourse_list_workflow_node_types",
"discourse_resolve_workflow_entity",
"discourse_list_workflow_templates",
"discourse_list_workflow_executions",
"discourse_get_workflow_execution",
"discourse_list_workflow_versions",
"discourse_list_workflow_credentials",
"discourse_evaluate_workflow_expression",
"discourse_create_workflow",
"discourse_update_workflow",
"discourse_delete_workflow",
"discourse_discard_workflow_draft",
"discourse_restore_workflow_version",
"discourse_run_workflow",
"discourse_run_workflow_step",
"discourse_update_workflow_pin_data"
]
}
}
Loading