@pidgeon-ai/mcp 0.28.2 → 1.0.0

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/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0
4
+
5
+ The MCP server for the new Pidgeon, run on your machine over stdio.
6
+
7
+ - Sets an agent up end to end: `sign_in` (Pidgeon's OAuth server, once, in
8
+ the browser), `set_up_agent` (registered, its key made here and published
9
+ signed with itself, the private key kept in a file and never shown to the
10
+ model), `create_agent_key`, `get_agent`, `get_reputation`, `list_agents`.
11
+ - Email: `list_inboxes`, `get_inbox`, `create_inbox`, `remove_inbox`,
12
+ `send_message`, `create_draft`, `get_draft`, `update_draft`, `delete_draft`,
13
+ `send_draft`, `request_approval`, `list_rules`, `add_rule`, `remove_rule`,
14
+ `list_suppressions`.
15
+ - `status`, `sign_out`, `list_events`.
package/LICENSE CHANGED
@@ -1,21 +1,55 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 PCN Labs OÜ
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ Apache License
2
+
3
+ Version 2.0, January 2004
4
+
5
+ http://www.apache.org/licenses/
6
+
7
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
8
+
9
+ 1. Definitions.
10
+
11
+ "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
16
+
17
+ "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
18
+
19
+ "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
20
+
21
+ "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
22
+
23
+ "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
24
+
25
+ "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
26
+
27
+ "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
28
+
29
+ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
30
+
31
+ 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
32
+
33
+ 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
34
+
35
+ 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
36
+
37
+ You must give any other recipients of the Work or Derivative Works a copy of this License; and
38
+
39
+ You must cause any modified files to carry prominent notices stating that You changed the files; and
40
+
41
+ You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
42
+
43
+ If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
44
+
45
+ 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
46
+
47
+ 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
48
+
49
+ 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
50
+
51
+ 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
52
+
53
+ 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
54
+
55
+ END OF TERMS AND CONDITIONS
package/README.md CHANGED
@@ -1,217 +1,50 @@
1
1
  # @pidgeon-ai/mcp
2
2
 
3
- An MCP server that gives your AI agent its own email inbox. Pidgeon is the
4
- email inbox API for AI agents. It gives agents their own inboxes so they can
5
- work with emails just like a human.
6
-
7
- Over [Model Context Protocol](https://modelcontextprotocol.io) an agent can
8
- create addresses, send, wait for a reply with its verification codes already
9
- pulled out, answer in the thread, and hand a conversation to a person. There
10
- are two ways in, and they are the same server.
11
-
12
- ## Hosted: a URL, and you sign in
13
-
14
- ```sh
15
- claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp
16
- ```
17
-
18
- The first call answers `401`, and the client sends you to Pidgeon to sign in
19
- with OAuth. You choose what it can do — read, read and send, or full access —
20
- and which addresses it can reach. Claude's custom connectors, ChatGPT, Cursor,
21
- Codex and VS Code take the same URL and sign in the same way. Nothing to
22
- install.
23
-
24
- For an agent with nobody there to sign in, send a key instead:
25
-
26
- ```sh
27
- claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp \
28
- --header "Authorization: Bearer $PIDGEON_API_KEY"
29
- ```
30
-
31
- The Claude Code, Codex, Cursor and Gemini CLI plugin installs the hosted
32
- server with a skill that teaches the agent to use it:
33
- [pidgeon-ai/pidgeon-plugins](https://github.com/pidgeon-ai/pidgeon-plugins).
34
-
35
- ## Or installed: this package
36
-
37
- For a client that runs MCP servers as local processes.
38
-
39
- ```sh
40
- PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp init
41
- ```
42
-
43
- That checks the key against the API and tells you which addresses it reaches
44
- — the one question a block of JSON cannot answer, and the one that otherwise
45
- surfaces as a model quietly getting an error you never see. Then it writes
46
- `.mcp.json` in the current directory and prints what it wrote.
47
-
48
- `--print` to see the config without writing it, which is what you want if your
49
- client keeps its own somewhere else. `--force` to replace an entry that is
50
- already there.
51
-
52
- For Codex, VS Code and Gemini CLI, `--client` writes the hosted server into
53
- that client's own file instead:
3
+ Pidgeon's MCP server. A coding agent sets an AI agent up end to end, with no
4
+ clicking past one sign-in: registered, its key made on your machine and
5
+ published, its reputation read, and an inbox to send from.
6
+ https://pidgeon.ai
54
7
 
55
8
  ```sh
56
- npx -y @pidgeon-ai/mcp init --client codex # ~/.codex/config.toml
57
- npx -y @pidgeon-ai/mcp init --client vscode # .vscode/mcp.json
58
- npx -y @pidgeon-ai/mcp init --client gemini # .gemini/settings.json
9
+ claude mcp add pidgeon -- npx -y @pidgeon-ai/mcp
59
10
  ```
60
11
 
61
- With no `PIDGEON_API_KEY` it writes the URL alone and the client signs you in
62
- (`codex mcp login pidgeon`, `/mcp auth pidgeon` in Gemini CLI, a browser
63
- prompt in VS Code). With a key it checks the key first and has the client read
64
- it from the variable, or ask for it once in VS Code, so it is never in the
65
- file. It keeps everything already in the file, comments included, backs a
66
- changed file up to `<file>.bak`, and is a no-op the second time. `--scope
67
- user|project` picks the other file; `--sign-in` ignores a key that is set.
68
-
69
- The key is referenced from the environment rather than written into the file,
70
- so the config can be committed and the credential cannot:
12
+ Any other client: run `npx -y @pidgeon-ai/mcp` over stdio, for example
71
13
 
72
14
  ```json
73
- {
74
- "mcpServers": {
75
- "pidgeon": {
76
- "command": "npx",
77
- "args": ["-y", "@pidgeon-ai/mcp"],
78
- "env": { "PIDGEON_API_KEY": "${PIDGEON_API_KEY}" }
79
- }
80
- }
81
- }
15
+ { "mcpServers": { "pidgeon": { "command": "npx", "args": ["-y", "@pidgeon-ai/mcp"] } } }
82
16
  ```
83
17
 
84
- A `pgn_live_…` key comes from
85
- [pidgeon.ai/app/developers/keys](https://pidgeon.ai/signup?utm_source=npm&utm_medium=readme&utm_campaign=mcp&next=/app/developers/keys). No
86
- account yet? An agent can sign itself up by reading
87
- [pidgeon.ai/skill.md](https://pidgeon.ai/skill.md); the only thing it needs
88
- from a person is a six-digit code.
18
+ Then ask: "Set up a Pidgeon agent called Booking agent that books tables, and
19
+ give it an inbox."
89
20
 
90
- `PIDGEON_BASE_URL` points it somewhere else, which is how you run it against a
91
- local checkout.
21
+ ## Why it runs on your machine
92
22
 
93
- Documentation: [pidgeon.ai/docs/mcp](https://pidgeon.ai/docs/mcp).
23
+ An agent's key must be made where the agent runs and never leave it.
24
+ `set_up_agent` makes the Ed25519 key here, publishes only the public half (in
25
+ a request signed with the key, which proves you hold it), and writes the
26
+ private half to `~/.config/pidgeon/agents/<id>.json`, readable by you only.
27
+ No tool ever answers a private key, so it never reaches the model.
94
28
 
95
- ## Tools
96
-
97
- <!-- tools:start -->
98
-
99
- | Tool | What it does |
100
- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
101
- | `get_setup` | Call this first. |
102
- | `list_addresses` | The addresses this credential can reach. |
103
- | `create_address` | Create an address for an agent to use. |
104
- | `get_address` | One address, by id. |
105
- | `list_threads` | Conversations in one address, newest first. |
106
- | `get_thread` | One conversation, by id. |
107
- | `list_messages` | The messages of one conversation, oldest first — the text to read before replying. |
108
- | `search_messages` | Full-text search across every address this credential can reach, ranked by relevance. |
109
- | `send_message` | Send from an address this credential may send as. |
110
- | `check_message` | Asks whether `send_message` with these arguments would go, and sends nothing. |
111
- | `verify_sender` | Checks a raw message, or its headers, and answers whether an AI agent sent it, on whose behalf, and whether the signatures on it hold: the signed agent declaration (`Agent-of`) and the `Post-Envelope`, from Pidgeon or any other signer using the same formats. |
112
- | `get_message` | One message, by id, with its body, the headers we keep, and what the sending domain’s records proved — `authentication.spf`, `.dkim`, `.dmarc`, where null means not reported rather than failed, and `.signature: "pass"` when another Pidgeon address sent it, signed and checked before it was stored. |
113
- | `await_message` | Waits until a message arrives at an address — after you submit a sign-up form, say — and returns it with `extracted.codes` and `extracted.links`: verification codes and confirm links, most likely first. |
114
- | `reply_to_message` | The recipients, the subject and the thread are read off the message being answered, so you bring the words and nothing else. |
115
- | `forward_message` | Sends one message on to somebody it was not addressed to, with its attachments, from the address that received it. |
116
- | `create_draft` | Writes a message without sending it, for a human to read and send — use it when you are asked to prepare replies for sign-off. |
117
- | `get_draft_approval` | Where a held send stands, by its `draft_id`: `pending` until a person approves or rejects it in the dashboard, then `approved` (it was sent, and `message_id` is the message), `rejected`, or `expired` after 24 hours with nobody deciding. |
118
- | `list_drafts` | Every draft at one address, newest first, with its recipients and body — so you can come back to one and finish it. |
119
- | `get_draft` | One draft by id: its sender, recipients, subject, text and attachments. |
120
- | `update_draft` | Changes the fields you pass and leaves the rest; `null` clears the subject or text. |
121
- | `delete_draft` | Deletes one draft, and cancels its send if it was scheduled. |
122
- | `schedule_draft` | Sends one draft later, from Pidgeon’s side, with no further call: it goes even if you and the person are offline. |
123
- | `unschedule_draft` | Takes a scheduled draft off the schedule. |
124
- | `read_attachment` | The text of one attachment — a CSV, a log, JSON, a calendar file, or a PDF, a Word `.docx` or an Excel `.xlsx`. |
125
- | `update_thread` | Who owns a conversation and where it has got to. |
126
- | `update_message` | Star a message, or move it to `archive`, `spam` or `trash`. |
127
- | `list_send_rules` | The allow and block list of one address, and the send policy it hangs off. |
128
- | `list_receive_rules` | The rules that decide what reaches one address — reject, spam, trash, archive or inbox, per sender or per domain — and its `receive_policy`. |
129
- | `list_folders` | Every folder of one address with its counts. |
130
- | `list_folder` | One folder of one address, newest first, a conversation per row — where `list_threads` says which conversations exist, this says where they are filed and what they look like in a list. |
131
- | `list_changes` | Everything that moved in one inbox since a `sync_cursor`, arrivals included, so a long-running agent does not re-read a folder to find one new message. |
132
- | `list_events` | Every event across every address this credential reaches — mail received, sent, delivered, bounced, filed. |
133
- | `list_labels` | Labels belong to an address, not to the workspace, so the same name on three addresses is three labels with three ids. |
134
- | `create_label` | A label on one address. |
135
- | `apply_label` | The label has to belong to the same address the conversation is in — `list_labels` for that address gives you the right id. |
136
- | `remove_label` | Removes one label from one conversation. |
137
- | `list_pods` | A pod is a container for one of your own customers: it holds addresses and domains, and **mail sent from it lands on its own sending reputation**, so one customer cannot damage another’s delivery. |
138
- | `create_pod` | A container for one of your customers, with its own sending reputation. |
139
- | `get_metrics` | Sent, delivered, bounced, rejected, complained, received and spam over a window of `days` — counted from the event log, so it includes outcomes the provider reported afterwards. |
140
- | `get_calendar` | The calendar of one address, by the address’s `id`: its default time zone and how many events it holds. |
141
- | `update_calendar` | The time zone an event created without one gets, as an IANA name like `Europe/Lisbon`. |
142
- | `get_agenda` | What is on an address’s calendar between `after` and `before` (ISO 8601 date-times), in start order, with each date of a recurring event listed on its own. |
143
- | `find_free_time` | When every address in `identity_ids` (comma-separated address ids, up to 10) is free between `after` and `before` (ISO 8601; default the next 7 days, 31 at most), in stretches at least `duration_minutes` long (default 30). |
144
- | `get_calendar_event` | One event by `eventId` on the calendar of address `id`: its times, description, location, recurrence, and its attendees with their answers. |
145
- | `create_calendar_event` | Puts an event on the calendar of address `id`. |
146
- | `update_calendar_event` | Changes one calendar event: the fields you pass, leaving the rest. |
147
- | `delete_calendar_event` | Removes an event from the calendar of address `id`. |
148
- | `respond_to_invitation` | Answers a meeting invitation that arrived as mail, by the message’s `id`: `accepted`, `declined` or `tentative`, with an optional `comment`. |
149
- | `find_contact` | Turns a name into an address: “email Priya” → `search: "priya"`. |
150
- | `update_contact` | Changes one contact by its `id` from `find_contact`: the fields you pass, leaving the rest. |
151
- | `block_contact` | From now on, mail from this contact to the address they are a contact of goes to spam, by the contact’s `id`. |
152
-
153
- <!-- tools:end -->
154
-
155
- ## Handing a conversation to a person
156
-
157
- `get_message`, `reply_to_message`, `update_message` and `update_thread` are
158
- the loop: read a message, answer it, file it, and say who owns it.
159
-
160
- ```
161
- update_thread id=<thread_id> owner_type=human
162
- ```
163
-
164
- It appears in the web inbox and `thread.updated` tells whatever was driving
165
- the conversation that it no longer is. `owner_type=agent` takes it back,
166
- `status` is the queue it sits in, and `assignee_id` names which person has it.
29
+ ## Signing in
167
30
 
168
- ## A retried send goes out once
31
+ The first tool that needs Pidgeon says so; `sign_in` opens the browser, where
32
+ you sign in to Pidgeon and choose what this machine may do. That is Pidgeon's
33
+ OAuth server, as MCP authorization describes it (discovery at
34
+ `/.well-known/oauth-protected-resource/mcp`, PKCE, a loopback redirect). The
35
+ session is refreshed from then on. On a machine with no browser, set
36
+ `PIDGEON_API_KEY` in the server's environment instead.
169
37
 
170
- `send_message` and `reply_to_message` take an `idempotency_key`. Reuse it
171
- when retrying the same send and it goes out once; the retry answers with
172
- the first send's result, after a line saying nothing was sent again. With
173
- no key, an identical call (same arguments, same credential) within the same
174
- clock hour counts as a retry. To send the same words twice on purpose
175
- inside that hour, pass a new key.
176
-
177
- ## Two settings worth knowing about
178
-
179
- An agent's address should usually be created **`reply_only`**: it can answer
180
- anybody who has written to it and start a conversation with nobody, which is a
181
- structural limit rather than a quantity. `create_address` takes it.
182
-
183
- It can also be given an **end date**. An address per ticket or per invoice
184
- stops accepting mail when the thing is over; expiry suspends the address and
185
- keeps the correspondence.
186
-
187
- ## The credential is the whole of the access control
188
-
189
- This hands a credential to a model. Nothing in this package decides what may
190
- be reached — the key's own ceiling and the addresses it was granted do all of
191
- it, server-side, exactly as for any other caller.
192
-
193
- So **give it the narrowest key the agent needs**. A key created with `read`
194
- access can never send, however generously it is granted an inbox, and an
195
- agent that only has to triage should have one.
196
-
197
- ## What this is not
198
-
199
- A protocol adapter over an API that already exists, and nothing else. No
200
- business logic, no database, no model, no state.
201
-
202
- Every tool **is** an endpoint: the dispatcher works off the endpoint each tool
203
- declares rather than off its name, so there is nowhere to put behaviour the
204
- API does not have, and a test asserts each one exists in the published
205
- OpenAPI document. If something is missing here, it is missing from the API,
206
- and that is where it gets built.
38
+ ## Tools
207
39
 
208
- ## Contributing
40
+ - **Passport:** `set_up_agent`, `create_agent_key`, `list_agents`,
41
+ `get_agent`, `get_reputation`
42
+ - **Email:** `list_inboxes`, `get_inbox`, `create_inbox`, `remove_inbox`,
43
+ `send_message`, `create_draft`, `get_draft`, `update_draft`,
44
+ `delete_draft`, `send_draft`, `request_approval`, `list_rules`, `add_rule`,
45
+ `remove_rule`, `list_suppressions`
46
+ - **The account:** `sign_in`, `sign_out`, `status`, `list_events`
209
47
 
210
- This package is published from
211
- [pidgeon-ai/pidgeon-js](https://github.com/pidgeon-ai/pidgeon-js), which is
212
- copied from Pidgeon's main repository on every release, so a pull request
213
- there cannot be merged as written.
214
- [Open an issue](https://github.com/pidgeon-ai/pidgeon-js/issues) and say what
215
- is wrong, or email [support@pidgeon.ai](mailto:support@pidgeon.ai).
48
+ ## License
216
49
 
217
- MIT licensed.
50
+ Apache-2.0
package/dist/bin.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/bin.js ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
3
+ import { createServer } from "./server.js";
4
+ // stdout is the protocol's: anything for a person goes to stderr.
5
+ await createServer().connect(new StdioServerTransport());
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Pidgeon's MCP server (MCP 1.0), run on the developer's machine over stdio.
3
+ *
4
+ * It runs here, not on pidgeon.ai, for one reason: an agent's key must be
5
+ * made where the agent runs and never leave it. `set_up_agent` registers the
6
+ * agent, makes its Ed25519 key on this machine, publishes the public half in
7
+ * a request signed with the key (the possession proof the dashboard sends),
8
+ * and writes the private half to a file only this user can read. No tool
9
+ * ever answers a private key, so it never reaches the model either.
10
+ *
11
+ * Signing in is Pidgeon's OAuth server, as MCP authorization describes it:
12
+ * `sign_in` opens the browser once, the person chooses what this machine may
13
+ * do, and the session is refreshed from then on. `PIDGEON_API_KEY` wins
14
+ * over a session, for machines with no browser.
15
+ */
16
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
17
+ import { VERSION } from './tools.ts';
18
+ export { VERSION };
19
+ export type Options = {
20
+ env?: Record<string, string | undefined>;
21
+ fetch?: typeof fetch;
22
+ /** Whether `sign_in` opens the browser itself (it always shows the address too). */
23
+ openBrowser?: boolean;
24
+ /** For tests: what a person does in the browser when signing in. */
25
+ onSignInUrl?: (url: string) => void;
26
+ };
27
+ export declare function createServer(options?: Options): McpServer;
package/dist/server.js ADDED
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Pidgeon's MCP server (MCP 1.0), run on the developer's machine over stdio.
3
+ *
4
+ * It runs here, not on pidgeon.ai, for one reason: an agent's key must be
5
+ * made where the agent runs and never leave it. `set_up_agent` registers the
6
+ * agent, makes its Ed25519 key on this machine, publishes the public half in
7
+ * a request signed with the key (the possession proof the dashboard sends),
8
+ * and writes the private half to a file only this user can read. No tool
9
+ * ever answers a private key, so it never reaches the model either.
10
+ *
11
+ * Signing in is Pidgeon's OAuth server, as MCP authorization describes it:
12
+ * `sign_in` opens the browser once, the person chooses what this machine may
13
+ * do, and the session is refreshed from then on. `PIDGEON_API_KEY` wins
14
+ * over a session, for machines with no browser.
15
+ */
16
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
17
+ import { z } from 'zod';
18
+ import { addAgentKey, baseUrlOf, clientFromEnvironment, listAgentKeys, readSession, setUpAgent, signIn, signOut, } from '@pidgeon-ai/sdk/node';
19
+ import { DESTROY, READ, registerApiTools, run, VERSION, WRITE } from "./tools.js";
20
+ export { VERSION };
21
+ const SIGN_IN_HINT = 'Call sign_in, which opens the browser for the person to approve.';
22
+ const answer = (work) => run(work, SIGN_IN_HINT);
23
+ const INSTRUCTIONS = `Pidgeon gives AI agents an identity apart from their owner: Passport (an agent's signing key and its operator's reputation), Bouncer (websites verify agents), Email (inboxes for agents) and Auth (Sign in with Pidgeon).
24
+
25
+ To set an agent up: sign_in if a tool says you are not signed in, then set_up_agent with a name and what it does. That registers it, makes its key on this machine, publishes the public half and keeps the private key in a file here; it is never shown to you. Then create_inbox with agent_id to give it an address, and get_reputation to see how websites will treat it.
26
+
27
+ Sending mail: send_message sends now; create_draft then request_approval when a person should look first. A message answered "held" waits for a person of the account.`;
28
+ export function createServer(options = {}) {
29
+ const env = options.env ?? process.env;
30
+ const baseUrl = baseUrlOf(env);
31
+ const pidgeon = clientFromEnvironment({ env, baseUrl, fetch: options.fetch });
32
+ const server = new McpServer({ name: 'pidgeon', title: 'Pidgeon', version: VERSION }, { instructions: INSTRUCTIONS });
33
+ // ------------------------------------------------------------ signing in
34
+ server.registerTool('sign_in', {
35
+ title: 'Sign in to Pidgeon',
36
+ description: 'Open the browser so the person signs in to Pidgeon and approves this machine. Waits until they answer (up to five minutes). `scope` is the most it asks for: admin sets agents and inboxes up, send sends mail, draft only drafts, read only reads.',
37
+ inputSchema: { scope: z.enum(['admin', 'send', 'draft', 'read']).default('admin') },
38
+ annotations: WRITE,
39
+ }, ({ scope }) => answer(async () => {
40
+ if (env.PIDGEON_API_KEY)
41
+ return {
42
+ signed_in: true,
43
+ with: 'PIDGEON_API_KEY',
44
+ note: 'An API key is set; it is used instead of a session.',
45
+ };
46
+ let shown = '';
47
+ const session = await signIn({
48
+ baseUrl,
49
+ scope,
50
+ env,
51
+ fetch: options.fetch,
52
+ clientName: 'Pidgeon MCP',
53
+ openBrowser: options.openBrowser ?? true,
54
+ onUrl: (url) => {
55
+ shown = url;
56
+ process.stderr.write(`Sign in to Pidgeon: ${url}\n`);
57
+ options.onSignInUrl?.(url);
58
+ },
59
+ });
60
+ return { signed_in: true, base_url: baseUrl, scope: session.scope, url_opened: shown };
61
+ }));
62
+ server.registerTool('sign_out', {
63
+ title: 'Sign out of Pidgeon',
64
+ description: 'End this machine’s session with Pidgeon and forget its tokens.',
65
+ annotations: DESTROY,
66
+ }, () => answer(async () => ({ signed_out: await signOut(baseUrl, { env, fetch: options.fetch }) })));
67
+ server.registerTool('status', {
68
+ title: 'Signed in?',
69
+ description: 'Whether this machine is signed in to Pidgeon, how, and the agent keys it keeps.',
70
+ annotations: READ,
71
+ }, () => answer(async () => {
72
+ const session = await readSession(baseUrl, env);
73
+ return {
74
+ base_url: baseUrl,
75
+ signed_in: Boolean(env.PIDGEON_API_KEY || session),
76
+ with: env.PIDGEON_API_KEY
77
+ ? 'PIDGEON_API_KEY'
78
+ : session
79
+ ? `a session (${session.scope})`
80
+ : null,
81
+ agent_keys_here: await listAgentKeys(env),
82
+ };
83
+ }));
84
+ // -------------------------------------------------------------- Passport
85
+ server.registerTool('set_up_agent', {
86
+ title: 'Set an agent up',
87
+ description: 'Register an agent, make its signing key on this machine, publish the public half (signed with the key, which proves it is held), and keep the private key in a file only this user can read. Answers the agent, its key id, its directory and the key file — never the key. The agent signs its requests with that file: `agentFromKeyFile(path)` in @pidgeon-ai/sdk/node, or PIDGEON_AGENT_KEY (the file’s private_jwk) and PIDGEON_DIRECTORY anywhere else.',
88
+ inputSchema: {
89
+ name: z.string().min(1).max(80).describe('What websites see the agent called.'),
90
+ purpose: z.string().max(280).optional().describe('What it does, in a sentence.'),
91
+ pod_id: z.string().uuid().optional(),
92
+ },
93
+ annotations: WRITE,
94
+ }, ({ name, purpose, pod_id }) => answer(async () => {
95
+ const made = await setUpAgent(pidgeon, { name, purpose, podId: pod_id }, env);
96
+ return {
97
+ agent: made.agent,
98
+ kid: made.kid,
99
+ key_file: made.keyFile,
100
+ directory: made.agent.directory,
101
+ next: 'create_inbox with agent_id gives it an address; get_reputation shows how websites see it.',
102
+ };
103
+ }));
104
+ server.registerTool('create_agent_key', {
105
+ title: 'Make a new key for an agent',
106
+ description: 'Make a new key on this machine for an agent already registered, publish it signed with itself, and keep it here, replacing the key file this machine had for the agent. The old key stays valid until it is revoked in the dashboard.',
107
+ inputSchema: { agent_id: z.string().uuid() },
108
+ annotations: WRITE,
109
+ }, ({ agent_id }) => answer(() => addAgentKey(pidgeon, agent_id, env)));
110
+ registerApiTools(server, pidgeon, SIGN_IN_HINT);
111
+ return server;
112
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The MCP tools that only call Pidgeon's API, shared by the server on the
3
+ * developer's machine (`server.ts`, stdio) and the hosted one at
4
+ * `https://pidgeon.ai/mcp`: reading agents and reputation, Email's inboxes,
5
+ * drafts and rules, and the event log. Nothing here touches the file system,
6
+ * so the app can run it. Tools that make keys live where keys are made.
7
+ */
8
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
9
+ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
10
+ import { type Pidgeon } from '@pidgeon-ai/sdk';
11
+ export declare const VERSION = "1.0.0";
12
+ export declare const json: (value: unknown) => CallToolResult;
13
+ export declare const failed: (text: string) => CallToolResult;
14
+ /** Run a tool's work and answer its result, or the API's refusal in words the model can act on. */
15
+ export declare function run(work: () => Promise<unknown>, signInHint?: string): Promise<CallToolResult>;
16
+ export declare const READ: {
17
+ readonly readOnlyHint: true;
18
+ readonly openWorldHint: true;
19
+ };
20
+ export declare const WRITE: {
21
+ readonly readOnlyHint: false;
22
+ readonly destructiveHint: false;
23
+ readonly openWorldHint: true;
24
+ };
25
+ export declare const DESTROY: {
26
+ readonly readOnlyHint: false;
27
+ readonly destructiveHint: true;
28
+ readonly openWorldHint: true;
29
+ };
30
+ /** Register every tool that is only an API call. `signInHint` is what to say when the caller is not signed in. */
31
+ export declare function registerApiTools(server: McpServer, pidgeon: Pidgeon, signInHint?: string): void;