PatchX Freenote Agent

PatchX Freenote was formerly called PatchXNote. Existing patchxnote-agent commands, patchxnote-mcp Skill installs, MCP configuration and credentials remain compatible.

English | 简体中文

Connect your synced PatchX Freenote records to AI assistants. Find records, review existing AI results, create Markdown drafts, and share approved content through webhooks.

Production service · MCP setup · Download App · User guide (Chinese)

Quickstart · Connection options · Skill · Usage examples · Troubleshooting · Reference

Published Channels

Channel	Public entry	What is available
npm	patchxnote-agent	Versioned CLI installer/launcher and bundled Skill; current release 0.2.15.
GitHub Release	v0.2.15	Six Windows/macOS/Linux binaries, checksums, and artifact attestations.
MCP official Registry	Search the retained ID · Version record	Registered as io.github.ZsTs119/patchxnote-agent.
Vercel skills.sh	patchxnote-mcp	New repository source, searchable as PatchX Freenote; Skill ID remains patchxnote-mcp.

These links show publication and directory listing. The 0.2.15 verification record documents artifact checks, Windows installation, local protocol discovery, and Registry readback; client/platform acceptance is tracked separately.

Choose Your Connection

Your environment	Use	Requirements
Desktop editor or local MCP host	npx -y patchxnote-agent@latest setup --client <client-id>	Node.js 18+, Windows/macOS/Linux on amd64 or arm64, and a PatchX Freenote account.
Platform that supports Remote MCP and OAuth	https://freenote.patch-x.cn/mcp	Configure a custom connector and complete that platform's authorization flow; no local Node.js installation is required for this route.
Assistant that supports Agent Skills	Install PatchX Freenote MCP Skill	Adds setup and usage instructions; complements the MCP connection.

Records must already be synced to PatchX Freenote and available to your account. Recorder-card connection, audio processing, and recording remain in the App/PC clients. Read records from the platform you select: mobile or desktop.

Quickstart

1. Set up your local client

If your assistant supports Agent Skills, install the Skill first. MCP setup also works without it. Choose one command for the client you use:

Client	Command
Cursor	npx -y patchxnote-agent@latest setup --client cursor
VS Code	npx -y patchxnote-agent@latest setup --client vscode
Codex	npx -y patchxnote-agent@latest setup --client codex
WorkBuddy desktop	npx -y patchxnote-agent@latest setup --client workbuddy

Setup checks browser OAuth login and writes or prints the appropriate MCP config. Run it in the same OS/runtime that will launch MCP: Windows desktop apps and WSL/remote sessions use different credential stores. See Client Setup for other clients and manual configuration.

2. Authorize in the browser

Complete the PatchX Freenote sign-in page opened by setup. Keep phone verification codes and credentials on that page. If you need to start browser login explicitly:

npx -y patchxnote-agent@latest mcp login

3. Verify and use

npx -y patchxnote-agent@latest mcp status --verify --output json

Refresh or restart your MCP client, let it discover the available tools, then ask: “Find up to five of today's mobile records.” A successful empty result is normal when that account/platform has no matching records. See Verify the Install for additional checks.

Using a hosted platform instead

Create a custom MCP connector named PatchX Freenote MCP, set its server URL to https://freenote.patch-x.cn/mcp, complete the platform's OAuth flow, and refresh its tool list. Follow the platform-specific instructions in client integration notes; support and acceptance vary by platform.

Help me connect PatchX Freenote MCP and install the PatchX Freenote MCP Skill when the client supports Agent Skills. Use the production service at https://freenote.patch-x.cn/ and the setup page at https://freenote.patch-x.cn/mcp/setup/; if existing configuration explicitly points to the old test service, update the server address used for this connection to production first. First, if this is a local command-capable environment, run npx -y patchxnote-agent@latest skill install on this machine so future or long sessions remember the PatchX Freenote SOP; if the current client does not support Skill installation, do not treat that as a connection blocker and continue with MCP setup according to the client's capabilities. Identify the MCP client you are running in: if this is a local MCP client such as Codex, Cursor, VS Code, Claude Desktop, Claude Code, or Windsurf, run npx -y patchxnote-agent@latest setup --client <client-id> on this machine in the same OS/runtime that will later launch the MCP server. If this is an AI client or cloud platform that cannot run local commands but supports Remote MCP, custom connectors, custom MCP services, or tool plugins, create a custom MCP connector named PatchX Freenote MCP and connect it with this PatchX Freenote Remote MCP URL: https://freenote.patch-x.cn/mcp. If you are not sure which client ID or config format to use, local clients should first run npx -y patchxnote-agent@latest mcp config and use the printed generic stdio config, while remote clients should look for a Remote MCP Server URL, MCP Server URL, or Custom Connector setup entry. For login, open the browser and let me complete PatchX Freenote phone-code authorization there; do not ask me to paste OTP codes, OAuth codes, authorization codes, access tokens, refresh tokens, or webhook secrets into chat. After setup, call patchxnote_get_current_user and patchxnote_list_memories with {"platform":"mobile","limit":5} to verify it works. References: https://github.com/ZsTs119/patchx-freenote-agent and https://patchx2025.feishu.cn/wiki/PnVRwYT7IirFPckairGcWPnHnCd

Common Workflows

Goal	Ask your assistant
Find synced records	“Find today's mobile records.”
Inspect an existing AI result	“Show the source text and saved AI result for this record.”
Prepare content to share	“Create a Markdown draft from this record. Let me review it before sending.”
Use a local webhook	“Send this approved Markdown to my Product Feishu webhook.”

An existing record/result is the input. Local draft files and local webhook aliases require the local tools that provide those capabilities; check the connected endpoint's tool list before using them.

PatchX Freenote MCP Skill

The Skill gives compatible assistants reusable setup, authorization, record lookup, result inspection, and approved webhook instructions. The npm package bundles it, so the recommended install does not require a separate GitHub clone:

npx -y patchxnote-agent@latest skill install

This installs the Skill into the user's .agents/skills/patchxnote-mcp directory by default. It does not log in to PatchX Freenote or start an MCP server.

Useful skill installer options:

Option	Use
--dry-run --json	Preview target paths and conflict status without writing files.
--home <path> or PATCHXNOTE_AGENT_SKILL_HOME=<path>	Install into a test or alternate home directory.
--agent universal|codex|cursor|claude-code|gemini-cli|github-copilot|all	Target a known local skill directory family after its location is verified.
--force	Replace an existing unmanaged or manually edited patchxnote-mcp skill after explicit user intent.

The installer is idempotent. If an existing patchxnote-mcp directory differs and is not managed by this package, it refuses to overwrite it unless --force is supplied. Managed installs include .patchxnote-agent-skill.json with the package version and source hash.

For users of the standard skills CLI, this Codex example installs from GitHub into the current project. It installs the Skill, not the MCP connection. Choose either this route or the npm-bundled install above.

npx -y skills add ZsTs119/patchx-freenote-agent --skill patchxnote-mcp --agent codex --yes

Login And MCP Modes

The client transport and the source of its tools are separate:

• mcp serve speaks stdio to the local client. In default auto mode, matching, unexpired browser OAuth credentials select a proxy to the hosted MCP service; otherwise it uses the local implementation.
• The local implementation provides 19 tool definitions in 0.2.15. Their data calls still require appropriate authentication. A proxied or directly connected hosted service supplies its own tool set and may differ.
• Use the connected endpoint's tools/list result as the source of truth for available tools. Local filesystem and webhook capabilities listed below describe the local implementation.
• mcp login is the browser OAuth entry. Terminal-only patchxnote login remains the separate legacy Agent login. mcp serve does not open a login browser when the editor starts.

Client Setup

Local setup supports these client IDs:

vscode, cursor, codex, claude-code, claude-desktop, windsurf, trae, qoder, workbuddy

vscode, cursor, codex, claude-desktop, and windsurf can write a local config file after confirmation. claude-code, trae, qoder, and workbuddy return manual commands or copyable config in V1. Platform clients such as Feishu Aily, Doubao Work Partner, Tencent Agent Development Platform, and enterprise WorkBuddy require the hosted remote MCP gateway and platform-console acceptance instead of local npx.

Useful setup flags:

patchxnote setup --client cursor --dry-run --print-config
patchxnote setup --client cursor --yes
patchxnote setup --client cursor --no-browser
patchxnote setup --all-local-supported --dry-run
patchxnote setup --client cursor --output json

Run setup in the same OS/runtime that will later launch MCP. For example, a Windows desktop editor needs Windows Credential Manager credentials, while a WSL or remote VS Code session needs credentials in that Linux runtime.

MCP Configuration

For generic local stdio MCP hosts, use the pure JSON printed by:

npx -y patchxnote-agent@latest mcp config

The default config looks like this:

{
  "mcpServers": {
    "patchxnote": {
      "command": "npx",
      "args": ["-y", "patchxnote-agent@latest", "mcp", "serve"]
    }
  }
}

Some clients may require a wrapper-specific field such as type: "stdio" or a different top-level key, but the command and args stay the same. If a client rejects npx, kills slow cold starts, or requires allowlisted absolute paths, use the fallback printed by:

npx -y patchxnote-agent@latest install --print-config

The fallback config uses the installed binary path:

{
  "mcpServers": {
    "patchxnote": {
      "command": "/absolute/path/to/patchxnote",
      "args": ["mcp", "serve"]
    }
  }
}

MCP Tools

Account And Record Lookup

Tool	Purpose
patchxnote_get_current_user	Show the current PatchX Freenote account status.
patchxnote_list_recorder_cards	List bound recorder cards with masked identifiers only.
patchxnote_get_quota_summary	Show current quota.
patchxnote_get_model_usage_summary	Show current-month AI usage and charged quota.
patchxnote_list_memories	List records for mobile or desktop.
patchxnote_search_memories	Search record basics cached in the current MCP session.
patchxnote_get_memory	Show safe basic information for one record.

Webhook Configuration And Sending

Tool	Purpose
patchxnote_list_webhook_targets	List local webhook aliases and masked metadata.
patchxnote_configure_webhook_target	Create or update a webhook alias; URL and secret inputs are write-only.
patchxnote_remove_webhook_target	Remove a webhook alias and best-effort clean up stored secrets.
patchxnote_list_webhook_templates	List built-in Markdown templates.
patchxnote_render_webhook_message	Render a record into Markdown and optionally save a local draft.
patchxnote_export_model_io	Export a complete AI processing record to a user-chosen local file.
patchxnote_send_webhook	Manually send Markdown, a draft, a rendered record, or a test message to target aliases.

AI Result Inspection

Tool	Purpose
patchxnote_list_model_io_traces	Find AI processing runs and the follow-up request_id.
patchxnote_get_model_io_source_text	Inspect or export the source text used for that run.
patchxnote_get_model_io_provider_response	Inspect or export the AI response.
patchxnote_get_model_io_parsed_result	Inspect or export the parsed AI result.
patchxnote_get_model_io_packaged_result	Inspect or export the final result.

Record tools require an explicit platform argument: mobile or desktop. The record list now includes formal saved results plus readable model-generated outputs when the server has model IO data. patchxnote model-io list remains the lower-level AI processing list for finding request IDs and filtering by task or state.

Webhook MCP tools share the same local config, keychain, templates, and sender modules as the CLI. They do not return full webhook URLs or signing secrets, and send calls perform external network requests only when the MCP client explicitly invokes the send tool.

AI result tools are explicit inspection tools. They may expose source text or AI payloads for the logged-in user, so use them only from trusted local MCP hosts. Large fields should be written to an explicit local out file.

CLI Commands

The examples below are independent commands. Choose the operation for your task; they are not one script to run from top to bottom.

Browser MCP login and local MCP service:

patchxnote version
patchxnote mcp login
patchxnote mcp status
patchxnote mcp config
patchxnote setup --client cursor
patchxnote mcp serve

Terminal CLI login:

patchxnote login
patchxnote auth status

List AI processing runs and export results:

patchxnote model-io list --platform mobile
patchxnote model-io source-text --request-id <request_id> --platform mobile --out ./source.txt
patchxnote model-io provider-response --request-id <request_id> --platform mobile --out ./provider-response.json
patchxnote model-io parsed-result --request-id <request_id> --platform mobile --out ./parsed-result.json
patchxnote model-io packaged-result --request-id <request_id> --platform mobile --out ./packaged-result.json
patchxnote model-io export --request-id <request_id> --platform mobile --out ./model-io.json

Get request_id from patchxnote model-io list --platform mobile|desktop when you need a lower-level AI processing run. MCP patchxnote_list_memories returns id and platform for record rendering, drafts, webhook workflows, and model IO field tools; for model-generated entries, that id can be the same value as request_id.

Configure and send webhooks:

patchxnote webhook set "Product Feishu" --type feishu --url-stdin
patchxnote webhook list
patchxnote webhook test "Product Feishu"
patchxnote webhook draft --memory-id <memory_id> --platform mobile --out ./patchxnote-drafts/example
patchxnote webhook send --target "Product Feishu" --file ./message.md
patchxnote webhook send --target "Product Feishu" --draft ./patchxnote-drafts/example
patchxnote webhook remove "Product Feishu"

Useful global flags:

--server-base-url <url>   PatchX Freenote API base URL
--profile <name>          local profile name
--output json             machine-readable output where supported
--config <path>           non-secret config file path

The npm package is a small installer/launcher wrapper:

npx -y patchxnote-agent@latest mcp login
npx -y patchxnote-agent@latest mcp status
npx -y patchxnote-agent@latest mcp config
npx -y patchxnote-agent@latest mcp serve
npx -y patchxnote-agent@latest skill install
npx -y patchxnote-agent@latest login
npx -y patchxnote-agent@latest setup --client cursor
npx -y patchxnote-agent@latest install
npx -y patchxnote-agent@latest update

Webhook URLs and optional Feishu/DingTalk signing secrets are stored in the local secure credential store, not in the non-secret config file. --url-stdin and --secret-stdin avoid shell history. CLI and MCP webhook sending is manual only, does not follow redirects, and surfaces provider errors directly.

patchxnote model-io export is the preferred complete AI processing export command. patchxnote webhook export-model-io remains available for compatibility.

Verify The Install

These checks do not sign you out or overwrite client configuration:

npm view patchxnote-agent@latest version --registry https://registry.npmjs.org
npx -y --registry https://registry.npmjs.org patchxnote-agent@latest skill install --dry-run --json
npx -y --registry https://registry.npmjs.org patchxnote-agent@latest mcp config
npx -y --registry https://registry.npmjs.org patchxnote-agent@latest mcp status --output json

After authorization, add --verify to mcp status to verify access. If the native binary is on PATH, patchxnote version reports its version and release commit. The current published release is 0.2.15.

Troubleshooting

Problem	What to check
patchxnote is not found after install	Add the printed install directory to PATH, then open a new terminal.
Login says credential storage is unavailable	Check that macOS Keychain, Windows Credential Manager, or Linux Secret Service is available and unlocked. For local development only, set PATCHXNOTE_AUTH_INSECURE_FILE_KEYCHAIN=true.
MCP login expired or points at the wrong server	Run npx -y patchxnote-agent@latest mcp logout --local-only, then run npx -y patchxnote-agent@latest mcp login again in the same runtime.
MCP host cannot start the server	If first start is slow or the client rejects npx, run npx -y patchxnote-agent@latest install --print-config once and use the printed absolute command path.
Setup writes credentials in the wrong place	Run setup from the same OS/runtime that will launch MCP. Windows desktop apps, WSL terminals, and VS Code Remote do not automatically share keychain credentials.
Need to undo setup	Restore the timestamped .bak-YYYYMMDDTHHMMSSZ file printed by setup, or remove only the patchxnote MCP server entry from the client config.
Record list is empty	Check that you selected the correct platform: mobile or desktop; use model-io list for lower-level AI processing runs.
Webhook did not send	Confirm the alias exists, the target is enabled, and check the provider error returned by the command.
Checksum verification fails	Retry later or pin a known version; the installer refuses unchecked binaries.
skill install says the target already exists and differs	The target contains an unmanaged or manually edited patchxnote-mcp skill. Inspect or back it up first; rerun with --force only when you want PatchX Freenote Agent to replace that skill folder.
Wrong server environment	Use --server-base-url <url> when logging in to another environment, and use a separate profile.
New release returns ETARGET	Check npm config get registry. A mirror may not have synced yet; use the one-command official-registry example below.

npx -y --registry https://registry.npmjs.org patchxnote-agent@latest install --print-config

This applies the registry choice to this command only. If a GitHub download is slow, retry later; the npm-bundled Skill avoids a separate repository clone.

Version 0.2.12 and later default to production. Existing explicit --server-base-url flags, PATCHXNOTE_SERVER_BASE_URL / legacy PATCHNOTE_SERVER_BASE_URL environment variables, and server.base_url config values override that default; update or remove test-server overrides in both the terminal and MCP host configuration.

Run mcp login in the same OS/runtime and profile that starts MCP, then check mcp status --verify. OAuth credentials are bound to the server address, so test login does not authenticate production. This update does not migrate test accounts or records. To keep both environments, use separate profiles and an explicit base URL for each.

Sign Out And Undo Setup

Choose the action you need; these are separate maintenance operations:

Action	Command or instructions
Sign out of MCP	npx -y patchxnote-agent@latest mcp logout
Remove only local MCP credentials	npx -y patchxnote-agent@latest mcp logout --local-only
Undo client setup	Restore the timestamped backup printed by setup, or remove its patchxnote entry from that client's configuration.
Uninstall the managed native binary	npx -y patchxnote-agent@latest uninstall

Security And Risk Notice