Skip to content

MCP Server

workers/mcp/ in the platform repo, deployed at:

https://mcp.freedocstore.online/mcp

A remote MCP server for agents that read, publish, and maintain FreeDocStore knowledge bases. Auth is OAuth 2.1 backed by GitHub sign-in; the server supports read and write token scopes.

Connect

claude mcp add --scope user --transport http freedocstore https://mcp.freedocstore.online/mcp

or:

codex mcp add freedocstore --url https://mcp.freedocstore.online/mcp

On first use the OAuth flow opens GitHub sign-in. The GitHub grant requests read:user public_repo — public_repo is what allows update_files to commit and open PRs as you. Sessions created before this scope existed must reconnect to grant it.

Tools

Tool Auth Description
whoami GitHub OAuth Show the signed-in account
workspace_summary GitHub OAuth Console workspace state: drafts, active KB, settings
list_workspace_drafts GitHub OAuth List KB drafts saved in the console workspace
create_workspace_draft OAuth + write Create a console-visible Zensical KB draft
create_sample_knowledge_base OAuth + write Create a sample KB draft for smoke testing
platform_guide none Publishing contract and current constraints
list_knowledge_bases none Read the public registry
knowledge_base_info none Repo, Cloudflare project, URLs, custom domains for one KB
check_zensical_repo none Validate a repo against the Zensical contract
list_files none List files in a public KB repo
read_file none Read one source file from a public KB repo
deploy_status none Last five GitHub Actions runs for a KB repo
publish_plan none Turn a topic into a concrete repo/Zensical/Cloudflare plan
update_files OAuth + write Edit KB repo files as the signed-in user — proposal PR by default, direct commit on request

Tools that take a repo accept an owner/name, a bare repo name under the FreeDocStore org, or a registry KB id.

update_files

update_files is the write path — the platform's prompt → proposal → diff → GitHub commit/PR rule as an MCP tool.

Parameters:

  • repo — target KB (registry id or repo name)
  • message — commit message
  • files — array of { path, content }, full replacement content per file
  • delete_paths — optional paths to delete
  • branch — base branch, default main
  • mode — "pr" (default) opens a pull request from a generated fds/mcp-* branch; "direct" commits straight to the base branch
  • pr_title, pr_body — optional PR copy

Commits are authored with the signed-in user's GitHub token — no shared bot identity. After a merge (or a direct commit), the KB's GitHub Actions workflow rebuilds and redeploys automatically; check progress with deploy_status.

Typical editing flow

  1. list_knowledge_bases → pick the KB.
  2. list_files / read_file → load current content.
  3. update_files with the changed Markdown → returns the PR URL.
  4. Review the diff on GitHub, merge.
  5. deploy_status → confirm the deploy ran.

Workspace access

The MCP worker shares the FDS_API_KV namespace with the API worker, so workspace_summary and the draft tools operate on the same per-user workspace the creator console shows.

Worker requirements

  • OAUTH_KV — OAuth request state and grants
  • FDS_API_KV — shared console workspace
  • GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET — the MCP GitHub OAuth app (callback https://mcp.freedocstore.online/callback)

Remaining planned write tools

  • create_knowledge_base — authenticated repo creation
  • register_custom_domain — custom-domain automation
  • publish_from_prompt — end-to-end topic → published KB