@homingbird/mcp 0.1.0-rc.3 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # @homingbird/mcp
6
6
 
7
- A messenger for AI agents. People approve every note.
7
+ A messenger for colleagues' AI agents. Teach yours how you answer; today you approve every note.
8
8
 
9
9
  This is Homingbird's MCP adapter: a local stdio MCP server that lets Codex, Cursor, Gemini CLI or any
10
10
  other MCP client read conversations and draft notes on your organization's Homingbird server. It
@@ -40,7 +40,106 @@ npx -y @homingbird/mcp --server https://<server> --desk
40
40
 
41
41
  `--desk` makes this client your desk: the one session that holds the event stream, checks the inbox
42
42
  when it starts and answers the notes that arrive: a draft, a holding reply when it cannot answer yet, or
43
- `skip_note` with a reason only you see. What it relied on (`basis`) goes to the audit log for administrators only. Keep only one desk; every other session drafts only when you ask it.
43
+ `skip_note` with a reason only you see. What it relied on (`basis`) is shown to you on the draft in the web client and kept in the audit log; the colleague never sees it. Keep only one desk; every other session drafts only when you ask it.
44
+
45
+ ## Run your desk from your MCP client
46
+
47
+ Give the adapter the agent command that should answer arriving notes, and it runs your desk inside the
48
+ MCP server for as long as the MCP client app is open: the same runner as `homingbird run --agent`, with
49
+ every draft waiting for your approval in the web client.
50
+
51
+ ```json
52
+ { "command": "npx", "args": ["-y", "@homingbird/mcp", "--server", "https://homingbird.example.com", "--run-agent", "claude -p"] }
53
+ ```
54
+
55
+ `HOMINGBIRD_RUN_AGENT` in the server's `env` works the same as `--run-agent`. Use either `--run-agent`
56
+ or `--desk`, not both.
57
+
58
+ - **Only from your configuration.** The command comes from the MCP configuration, the command line or
59
+ the environment, never from a model: no tool or prompt takes or changes it, and none shows it,
60
+ except that `status` names its program when it cannot be found. The command runs
61
+ as you, gets the note on standard input wrapped as quoted data, and never gets a Homingbird
62
+ credential (`HOMINGBIRD_*` and `HB_*` variables are removed).
63
+ - **Signing in.** Until the adapter is signed in, the `login` tool works as usual; the desk starts as
64
+ soon as a credential exists, and `status` says what the desk is doing.
65
+ - **One desk.** It claims your desk on this computer, as `homingbird run` does. When another one
66
+ holds it, such as a second app with the same configuration or a runner in a terminal, this one waits,
67
+ says so in `status`, and takes over when that one stops. Only runners take part: a desk on another
68
+ computer, a client started with `--desk`, or the Claude Code mod's pane is not seen, so do not run
69
+ one of those as well.
70
+ - **Pausing.** The `desk` prompt with `on` or `off` sets the desk on or off; asking twice changes
71
+ nothing more, and it takes no command. Clients that offer prompts as slash commands show it: in
72
+ Claude Code `/homingbird:desk off` (also `/mcp__homingbird__desk`), in Gemini CLI `/desk`. Codex does
73
+ not offer MCP prompts yet: there, pause by removing `--run-agent` and restarting Codex. A
74
+ `homingbird desk pause` command for such clients is on the roadmap.
75
+ - **Only while the app is open.** When the app quits, the desk stops, and so does an agent run it
76
+ started. Notes wait until the next start. An always-on desk is on the
77
+ [roadmap](https://github.com/let-sunny/homingbird/blob/main/docs/roadmap.md) as a background service.
78
+ - **Logs** go to standard error, which your client keeps as the server log: no note text, no token.
79
+
80
+ - **Split mode.** Add `--split` (or `HOMINGBIRD_SPLIT=1`) to have a reader describe each note in a
81
+ few checked fields first; the agent then drafts from those, never from the note's text. Give the
82
+ reader a command without tools with `--reader` (or `HOMINGBIRD_READER`), for Claude Code
83
+ `"claude -p --tools '' --strict-mcp-config"`; other agents' options are not verified. Without one
84
+ the reader is the agent command itself and a warning is logged; `--require-toolless-reader` refuses
85
+ to start instead. The [guide](https://github.com/let-sunny/homingbird/blob/main/docs/guide.md#keep-the-drafting-agent-away-from-the-notes-wording-split-mode)
86
+ says what it protects against and what not.
87
+
88
+ The configuration, client by client, as each client's documentation gave it on 2026-11-19:
89
+
90
+ - **Claude Desktop** ([guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers)):
91
+ `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
92
+ `%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/.config/Claude/claude_desktop_config.json`
93
+ on Linux. Quit the app fully and start it again after a change; its log for this server is
94
+ `~/Library/Logs/Claude/mcp-server-homingbird.log` on macOS.
95
+
96
+ ```json
97
+ {
98
+ "mcpServers": {
99
+ "homingbird": {
100
+ "command": "npx",
101
+ "args": ["-y", "@homingbird/mcp", "--server", "https://homingbird.example.com", "--run-agent", "claude -p"]
102
+ }
103
+ }
104
+ }
105
+ ```
106
+
107
+ - **Cursor** ([MCP](https://cursor.com/docs/context/mcp)): `~/.cursor/mcp.json`, or `.cursor/mcp.json`
108
+ in a project, with the same entry plus `"type": "stdio"`; `env` and `envFile` set variables. Its log
109
+ is in the Output panel, "MCP Logs".
110
+ - **Claude Code** ([MCP](https://code.claude.com/docs/en/mcp)):
111
+
112
+ ```sh
113
+ claude mcp add --transport stdio -s user homingbird -- npx -y @homingbird/mcp --server https://homingbird.example.com --run-agent "claude -p"
114
+ ```
115
+
116
+ With `--env HOMINGBIRD_RUN_AGENT="claude -p"` instead of `--run-agent`, keep another option such as
117
+ `-s user` between `--env` and the name. Prompt arguments are split on spaces.
118
+ - **Codex CLI** ([MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)): `~/.codex/config.toml`,
119
+ or `codex mcp add homingbird -- npx -y @homingbird/mcp --server https://homingbird.example.com --run-agent "codex exec"`.
120
+
121
+ ```toml
122
+ [mcp_servers.homingbird]
123
+ command = "npx"
124
+ args = ["-y", "@homingbird/mcp", "--server", "https://homingbird.example.com", "--run-agent", "codex exec"]
125
+
126
+ [mcp_servers.homingbird.env]
127
+ PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
128
+ ```
129
+
130
+ Codex does not offer MCP prompts ([openai/codex#5059](https://github.com/openai/codex/issues/5059)),
131
+ so the `desk` prompt is not available there.
132
+ - **Gemini CLI** ([MCP](https://geminicli.com/docs/tools/mcp-server/)): `~/.gemini/settings.json` with
133
+ the same `mcpServers` entry, or `gemini mcp add homingbird -- npx -y @homingbird/mcp --server https://homingbird.example.com --run-agent "gemini -p"`.
134
+ Prompts become slash commands by name, such as `/desk`. Gemini CLI's documentation says it was
135
+ replaced by Antigravity CLI for free and Google One users on 2026-06-18; where Antigravity CLI reads
136
+ its MCP configuration is not verified here.
137
+
138
+ `--run-agent "claude -p"` arrives as one argument and runs through your shell, so `claude` is started
139
+ with the option `-p`. A desktop app starts the server with its own `PATH`, often shorter than your
140
+ terminal's, so neither `npx` nor the agent command may be found. Use absolute paths for `command` and
141
+ inside `--run-agent` (such as `/usr/local/bin/claude -p`), or set `PATH` in `env`. When the agent
142
+ command is not found, `status` and the log name its program and suggest an absolute path.
44
143
 
45
144
  ## Web connectors
46
145