Skip to content

AI_SETUP.en.md

Latest commit

 

History

History
124 lines (86 loc) · 6.53 KB

AI_SETUP.en.md

File metadata and controls

124 lines (86 loc) · 6.53 KB
Raw

无线麦SayAll.app: AI Installation and MCP Setup Guide

This document is written for AI agents such as Codex, Claude Code, Cursor, and OpenCode. It explains how to configure 无线麦SayAll.app and its local, read-only transcript-history MCP without requiring Node.js, npm, Homebrew, Xcode, or another development runtime.

Mandatory consent boundaries

  • Local Agent Access is off by default. An AI must not silently enable it or bypass the confirmation inside 无线麦SayAll.app.
  • Configure a client only after the user explicitly asks to connect that client.
  • Never ask the user to paste an access token into chat, an issue, logs, or a public file. Do not echo or upload the token.
  • The MCP can only read Reflections history. It cannot create, edit, or delete entries.
  • 无线麦SayAll.app and its bundled Helper do not upload history. The connected AI client may send returned text to its own provider, so remind the user to review that provider's data policy.

1. Verify the complete app

Default app location:

/Applications/SayAll.app

Bundled Swift MCP Helper:

/Applications/SayAll.app/Contents/Helpers/SayAllMCP

Verify that both exist and that the Helper is executable. If the Helper is missing, reinstall the complete app. Do not replace it with Node.js or a source checkout.

2. Ask the user to grant access

The user must perform these actions in 无线麦SayAll.app:

  1. Open Reflections in the sidebar.
  2. Turn on Save to Reflections if new speech-to-text history should be recorded.
  3. Find Local Agent Access lower on the page and turn on Allow Access.
  4. Under Connect AI Tools, select Connect for the intended client.
  5. Quit and reopen that client after the connection succeeds; 无线麦SayAll.app does not need to restart.

Quick connection supports Codex, Claude Code, Cursor, and OpenCode. It creates a separate read-only authorization per client and makes a private backup before changing an existing configuration. It will not overwrite a conflicting server, invalid JSON, or commented JSONC.

Quick connection validates the client entry point and configuration before creating an authorization. A failed preflight or installation does not leave duplicate entries under Authorized Clients. Each client can have only one active quick connection, and the page reports the specific failure reason.

3. Verify quick connection first

After reopening the client, verify that an MCP server named sayall_history exists, then check:

  1. MCP initialize succeeds.
  2. tools/list contains list_transcript_apps and query_transcripts.
  3. list_transcript_apps returns app summaries without transcript text.
  4. query_transcripts with a small limit returns a local test entry the user allowed the client to read.

Failure while the global switch is off or an authorization is revoked is expected. Do not attempt to bypass it.

4. Manual fallback

In Other Clients or Manual Setup, ask the user to enter a client name and select Create Read-Only Access. Paste the generated configuration directly into the intended local client configuration. The token is shown once.

Codex

Use ~/.codex/config.toml and copy Codex TOML from the app:

[mcp_servers.sayall_history]
command = "/Applications/SayAll.app/Contents/Helpers/SayAllMCP"
args = ["serve"]
env = { SAYALL_MCP_CLIENT_ID = "<generated by the app>", SAYALL_MCP_ACCESS_TOKEN = "<generated by the app>" }

Claude Code

Copy the standard MCP JSON, extract the sayall_history server object, and use the official user-scoped command:

claude mcp add-json --scope user sayall_history '<stdio server JSON>'

Do not retain the real token in terminal history, chat, or a script. Restart Claude Code and use claude mcp get sayall_history to inspect the result.

Cursor

Merge mcpServers.sayall_history from the generated standard JSON into ~/.cursor/mcp.json, preserving every other server. If the file is JSONC, contains comments, or cannot be parsed, do not rewrite the complete file; have the user add it through Cursor settings.

OpenCode

Merge the following shape into ~/.config/opencode/opencode.json, preserving existing mcp entries:

{
  "mcp": {
    "sayall_history": {
      "type": "local",
      "command": [
        "/Applications/SayAll.app/Contents/Helpers/SayAllMCP",
        "serve"
      ],
      "environment": {
        "SAYALL_MCP_CLIENT_ID": "<generated by the app>",
        "SAYALL_MCP_ACCESS_TOKEN": "<generated by the app>"
      },
      "enabled": true
    }
  }
}

Do not automatically rewrite JSONC or an invalid configuration.

5. Troubleshooting

  • No quick-connect cards: install a complete newer build that includes this feature.
  • Client says it is not detected: install that client and reopen Reflections.
  • Codex reports missing escaped value: check whether an older test build wrote a Helper path containing \/; revoke that authorization and reconnect with the fixed 无线麦SayAll.app. Never reuse a token pasted into chat or another public location.
  • Same-name conflict: inspect the existing sayall_history entry and do not overwrite a user-managed server. Use manual setup or let the user remove the conflict.
  • Missing or non-executable Helper: reinstall the complete app.
  • App location changed: the old configuration still points to the previous Helper. Remove that connection in 无线麦SayAll.app, then connect it again; do not overwrite unrelated MCP servers.
  • Connected but reads fail: confirm Allow Access is still on, the client authorization is active, and Reflections contains history.
  • App moved elsewhere: the absolute Helper path in old configurations is no longer valid. Move the app back to /Applications, or remove and reconnect the client.
  • Client no longer needed: remove it from its card or the authorized-client list. Turning off the global switch blocks every client immediately without deleting history.

6. Compatibility and privacy

The published v1 contract keeps the bundled Helper path, serve argument, two environment variables, and the released semantics of list_transcript_apps and query_transcripts backward-compatible. Future optional capabilities will not require a programming environment.

History and authorization state remain in the current macOS user's Application Support. The authorization store keeps only token and Helper-path hashes, not the plaintext token or original App path. Client configurations must hold the actual token and Helper path to start the local MCP, so those files must stay private and must never be committed to a public repository.