@pidgeon-ai/mcp 0.29.0 → 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 +15 -0
- package/LICENSE +55 -21
- package/README.md +32 -209
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +5 -0
- package/dist/server.d.ts +27 -0
- package/dist/server.js +112 -0
- package/dist/tools.d.ts +31 -0
- package/dist/tools.js +204 -0
- package/package.json +30 -43
- package/server.json +8 -63
- package/dist/chunk-67QGOBKE.js +0 -267
- package/dist/chunk-67QGOBKE.js.map +0 -1
- package/dist/chunk-6HW5LN74.js +0 -1365
- package/dist/chunk-6HW5LN74.js.map +0 -1
- package/dist/cli.d.ts +0 -2
- package/dist/cli.js +0 -8
- package/dist/cli.js.map +0 -1
- package/dist/clients-N7HG6WUL.js +0 -24
- package/dist/clients-N7HG6WUL.js.map +0 -1
- package/dist/index.d.ts +0 -107
- package/dist/index.js +0 -14
- package/dist/index.js.map +0 -1
- package/dist/init-TDXCNVQ5.js +0 -246
- package/dist/init-TDXCNVQ5.js.map +0 -1
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
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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,227 +1,50 @@
|
|
|
1
1
|
# @pidgeon-ai/mcp
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
85
|
-
|
|
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
|
-
|
|
91
|
-
local checkout.
|
|
21
|
+
## Why it runs on your machine
|
|
92
22
|
|
|
93
|
-
|
|
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
|
-
##
|
|
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
|
-
| `list_domains` | The domains this account sends from, with `status` (`verified` or still waiting on DNS) and `pod_id`, the pod each one sends from. |
|
|
140
|
-
| `add_domain` | Adds a domain to send from, such as `team.example.com`, and answers the DNS `dns_records` to publish where its DNS is kept. |
|
|
141
|
-
| `get_domain` | One domain, by id, with every DNS record it needs and whether each is found yet. |
|
|
142
|
-
| `verify_domain` | Looks the domain’s DNS up now and answers whether it is verified and which records are still missing or wrong. |
|
|
143
|
-
| `list_api_keys` | This account’s keys: name, prefix, what each may reach (`pod_id`, `identity_ids` or every address), its `access`, when it was last used, and whether it is revoked. |
|
|
144
|
-
| `create_api_key` | A new key for a server or another agent. |
|
|
145
|
-
| `revoke_api_key` | Stops a key working, at once and for good, with every key it made. |
|
|
146
|
-
| `list_webhooks` | The URLs this account posts events to, which address and events each one hears, and whether deliveries are failing. |
|
|
147
|
-
| `create_webhook` | Posts events to `url` as they happen. |
|
|
148
|
-
| `delete_webhook` | Stops posting to that URL. |
|
|
149
|
-
| `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. |
|
|
150
|
-
| `get_calendar` | The calendar of one address, by the address’s `id`: its default time zone and how many events it holds. |
|
|
151
|
-
| `update_calendar` | The time zone an event created without one gets, as an IANA name like `Europe/Lisbon`. |
|
|
152
|
-
| `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. |
|
|
153
|
-
| `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). |
|
|
154
|
-
| `get_calendar_event` | One event by `eventId` on the calendar of address `id`: its times, description, location, recurrence, and its attendees with their answers. |
|
|
155
|
-
| `create_calendar_event` | Puts an event on the calendar of address `id`. |
|
|
156
|
-
| `update_calendar_event` | Changes one calendar event: the fields you pass, leaving the rest. |
|
|
157
|
-
| `delete_calendar_event` | Removes an event from the calendar of address `id`. |
|
|
158
|
-
| `respond_to_invitation` | Answers a meeting invitation that arrived as mail, by the message’s `id`: `accepted`, `declined` or `tentative`, with an optional `comment`. |
|
|
159
|
-
| `find_contact` | Turns a name into an address: “email Priya” → `search: "priya"`. |
|
|
160
|
-
| `update_contact` | Changes one contact by its `id` from `find_contact`: the fields you pass, leaving the rest. |
|
|
161
|
-
| `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`. |
|
|
162
|
-
|
|
163
|
-
<!-- tools:end -->
|
|
164
|
-
|
|
165
|
-
## Handing a conversation to a person
|
|
166
|
-
|
|
167
|
-
`get_message`, `reply_to_message`, `update_message` and `update_thread` are
|
|
168
|
-
the loop: read a message, answer it, file it, and say who owns it.
|
|
169
|
-
|
|
170
|
-
```
|
|
171
|
-
update_thread id=<thread_id> owner_type=human
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
It appears in the web inbox and `thread.updated` tells whatever was driving
|
|
175
|
-
the conversation that it no longer is. `owner_type=agent` takes it back,
|
|
176
|
-
`status` is the queue it sits in, and `assignee_id` names which person has it.
|
|
29
|
+
## Signing in
|
|
177
30
|
|
|
178
|
-
|
|
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.
|
|
179
37
|
|
|
180
|
-
|
|
181
|
-
when retrying the same send and it goes out once; the retry answers with
|
|
182
|
-
the first send's result, after a line saying nothing was sent again. With
|
|
183
|
-
no key, an identical call (same arguments, same credential) within the same
|
|
184
|
-
clock hour counts as a retry. To send the same words twice on purpose
|
|
185
|
-
inside that hour, pass a new key.
|
|
186
|
-
|
|
187
|
-
## Two settings worth knowing about
|
|
188
|
-
|
|
189
|
-
An agent's address should usually be created **`reply_only`**: it can answer
|
|
190
|
-
anybody who has written to it and start a conversation with nobody, which is a
|
|
191
|
-
structural limit rather than a quantity. `create_address` takes it.
|
|
192
|
-
|
|
193
|
-
It can also be given an **end date**. An address per ticket or per invoice
|
|
194
|
-
stops accepting mail when the thing is over; expiry suspends the address and
|
|
195
|
-
keeps the correspondence.
|
|
196
|
-
|
|
197
|
-
## The credential is the whole of the access control
|
|
198
|
-
|
|
199
|
-
This hands a credential to a model. Nothing in this package decides what may
|
|
200
|
-
be reached — the key's own ceiling and the addresses it was granted do all of
|
|
201
|
-
it, server-side, exactly as for any other caller.
|
|
202
|
-
|
|
203
|
-
So **give it the narrowest key the agent needs**. A key created with `read`
|
|
204
|
-
access can never send, however generously it is granted an inbox, and an
|
|
205
|
-
agent that only has to triage should have one.
|
|
206
|
-
|
|
207
|
-
## What this is not
|
|
208
|
-
|
|
209
|
-
A protocol adapter over an API that already exists, and nothing else. No
|
|
210
|
-
business logic, no database, no model, no state.
|
|
211
|
-
|
|
212
|
-
Every tool **is** an endpoint: the dispatcher works off the endpoint each tool
|
|
213
|
-
declares rather than off its name, so there is nowhere to put behaviour the
|
|
214
|
-
API does not have, and a test asserts each one exists in the published
|
|
215
|
-
OpenAPI document. If something is missing here, it is missing from the API,
|
|
216
|
-
and that is where it gets built.
|
|
38
|
+
## Tools
|
|
217
39
|
|
|
218
|
-
|
|
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`
|
|
219
47
|
|
|
220
|
-
|
|
221
|
-
[pidgeon-ai/pidgeon-js](https://github.com/pidgeon-ai/pidgeon-js), which is
|
|
222
|
-
copied from Pidgeon's main repository on every release, so a pull request
|
|
223
|
-
there cannot be merged as written.
|
|
224
|
-
[Open an issue](https://github.com/pidgeon-ai/pidgeon-js/issues) and say what
|
|
225
|
-
is wrong, or email [support@pidgeon.ai](mailto:support@pidgeon.ai).
|
|
48
|
+
## License
|
|
226
49
|
|
|
227
|
-
|
|
50
|
+
Apache-2.0
|
package/dist/bin.d.ts
ADDED
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());
|
package/dist/server.d.ts
ADDED
|
@@ -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
|
+
}
|
package/dist/tools.d.ts
ADDED
|
@@ -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;
|