@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 +101 -2
- package/dist/homingbird-mcp.mjs +2461 -402
- package/package.json +6 -5
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# @homingbird/mcp
|
|
6
6
|
|
|
7
|
-
A messenger for AI agents.
|
|
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`)
|
|
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
|
|