@honu-office/mcp 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +203 -2
- package/package.json +58 -4
- package/src/config.js +214 -0
- package/src/files.js +108 -0
- package/src/http.js +238 -0
- package/src/index.js +33 -0
- package/src/poll.js +80 -0
- package/src/server.js +159 -0
- package/src/tools/analyze.js +177 -0
- package/src/tools/convert.js +97 -0
- package/src/tools/discover.js +109 -0
- package/src/tools/remediate.js +140 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AFixt
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,3 +1,204 @@
|
|
|
1
|
-
#
|
|
1
|
+
# HonuOffice MCP server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An [MCP](https://modelcontextprotocol.io) server that gives Claude the same document
|
|
4
|
+
accessibility capabilities you get at [officea11y.com](https://officea11y.com): analyze a
|
|
5
|
+
document, convert it, discover documents across a site, and submit one for remediation.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Requires **Node.js 22 or newer**.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @honu-office/mcp
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Or run it without installing, once published:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx -y @honu-office/mcp
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Configure
|
|
22
|
+
|
|
23
|
+
You need an API key: sign in at officea11y.com and create one under **Account → API keys**.
|
|
24
|
+
|
|
25
|
+
### Claude Desktop
|
|
26
|
+
|
|
27
|
+
Add this to your `claude_desktop_config.json`:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"mcpServers": {
|
|
32
|
+
"honu-office": {
|
|
33
|
+
"command": "npx",
|
|
34
|
+
"args": ["-y", "@honu-office/mcp"],
|
|
35
|
+
"env": {
|
|
36
|
+
"HONU_OFFICE_API_KEY": "your-api-key"
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The file lives at:
|
|
44
|
+
|
|
45
|
+
- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
46
|
+
- **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`
|
|
47
|
+
|
|
48
|
+
Restart Claude Desktop afterwards.
|
|
49
|
+
|
|
50
|
+
### Claude Code
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
claude mcp add honu-office --env HONU_OFFICE_API_KEY=your-api-key -- npx -y @honu-office/mcp
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Environment
|
|
57
|
+
|
|
58
|
+
| Variable | Required | Default | Purpose |
|
|
59
|
+
| --- | --- | --- | --- |
|
|
60
|
+
| `HONU_OFFICE_API_KEY` | yes | — | Your API key |
|
|
61
|
+
| `HONU_OFFICE_BASE_URL` | no | `https://officea11y.com` | Point at another environment |
|
|
62
|
+
| `HONU_OFFICE_TIMEOUT_MS` | no | `180000` | How long to wait for an asynchronous job overall |
|
|
63
|
+
| `HONU_OFFICE_REQUEST_TIMEOUT_MS` | no | `60000` | Deadline for any single HTTP request |
|
|
64
|
+
| `HONU_OFFICE_UPLOAD_TIMEOUT_MS` | no | `300000` | Deadline for an upload, which can legitimately take longer |
|
|
65
|
+
|
|
66
|
+
These were named `OFFICEA11Y_*` before the product became Honu Office. Those
|
|
67
|
+
names live in your MCP client's configuration, which this package cannot edit,
|
|
68
|
+
so they are still read: the `HONU_OFFICE_` name wins when both are set, and a
|
|
69
|
+
value arriving under the old name prints one line on stderr naming what to
|
|
70
|
+
rename. They will stop being read in a future release.
|
|
71
|
+
|
|
72
|
+
The default base URL still points at the previous origin. It moves when the new
|
|
73
|
+
domain has a DNS record, not before.
|
|
74
|
+
|
|
75
|
+
## Tools
|
|
76
|
+
|
|
77
|
+
### `analyze`
|
|
78
|
+
|
|
79
|
+
Check a document against PDF/UA and WCAG. Takes a **file path on your machine** or a
|
|
80
|
+
**URL**, and returns the score, issue counts by severity, and the most severe issues.
|
|
81
|
+
|
|
82
|
+
> Analyze ~/Documents/annual-report.pdf and tell me what's wrong with it
|
|
83
|
+
|
|
84
|
+
Analysis is asynchronous; the tool waits for the result rather than handing back a job id.
|
|
85
|
+
Pass `wait: false` if you would rather have the id immediately.
|
|
86
|
+
|
|
87
|
+
### `convert`
|
|
88
|
+
|
|
89
|
+
Convert a document — PDF to Word, or to HTML, text, RTF, EPUB or Markdown. Returns the
|
|
90
|
+
download location when the conversion finishes.
|
|
91
|
+
|
|
92
|
+
> Convert ~/Documents/report.pdf to Word
|
|
93
|
+
|
|
94
|
+
Ask for `list_formats` to see which conversions are supported.
|
|
95
|
+
|
|
96
|
+
### `discover`
|
|
97
|
+
|
|
98
|
+
Crawl a site to find documents. Crawls are long-running, so this does **not** wait:
|
|
99
|
+
start one, then check its status and list what it found.
|
|
100
|
+
|
|
101
|
+
> Find every PDF on example.com, then tell me when it's done
|
|
102
|
+
|
|
103
|
+
Actions: `start` (needs `url`), `status` and `documents` (need `jobId`), `list`.
|
|
104
|
+
|
|
105
|
+
### `remediate`
|
|
106
|
+
|
|
107
|
+
Submit a document to be fixed. Takes a file, a URL, or the `reportId` from a previous
|
|
108
|
+
`analyze` call — so "now fix it" does not re-upload the document.
|
|
109
|
+
|
|
110
|
+
> Analyze this PDF, then submit it for remediation
|
|
111
|
+
|
|
112
|
+
Remediation is worked on over time, so this returns a request id and any quote rather than
|
|
113
|
+
waiting. Actions: `submit`, `status` (needs `requestId`), `list`.
|
|
114
|
+
|
|
115
|
+
## Notes
|
|
116
|
+
|
|
117
|
+
**Your documents are uploaded to HonuOffice.** The server runs locally and reads the paths
|
|
118
|
+
you give it, but analysis, conversion and remediation all happen server-side. Do not point
|
|
119
|
+
it at anything you would not upload.
|
|
120
|
+
|
|
121
|
+
**Errors distinguish two different problems.** "HonuOffice rejected the request" and "I
|
|
122
|
+
could not reach HonuOffice" get different messages, because they need different responses
|
|
123
|
+
from you — a wrong key versus a network or host problem.
|
|
124
|
+
|
|
125
|
+
**Every request has a deadline.** Node's `fetch` does not impose a usable one: a server
|
|
126
|
+
that accepts the connection and then says nothing leaves a request outstanding
|
|
127
|
+
indefinitely. For an MCP server that is worse than an error, because the agent just waits
|
|
128
|
+
and you see the client freeze with nothing to act on. Requests are bounded at 60s and
|
|
129
|
+
uploads at 300s; both are configurable above.
|
|
130
|
+
|
|
131
|
+
**It does not write to your filesystem.** `convert` reports where to download the result
|
|
132
|
+
rather than choosing a destination for you.
|
|
133
|
+
|
|
134
|
+
## Development
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
npm install
|
|
138
|
+
npm run hooks:install # install the git hooks (once per clone)
|
|
139
|
+
npm test # 79 tests, no network required
|
|
140
|
+
npm run smoke # launch the binary and speak MCP to it over stdio
|
|
141
|
+
npm run check # markdown lint + tests + smoke
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Against a real API (opt-in, needs a key):
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
HONU_OFFICE_API_KEY=... HONU_OFFICE_BASE_URL=http://localhost:3002 \
|
|
148
|
+
npm run verify:live -- ./some.pdf
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Checks
|
|
152
|
+
|
|
153
|
+
`npm run check` is what both the pre-push hook and CI run, so they cannot drift.
|
|
154
|
+
|
|
155
|
+
`npm run verify:live` is **not** part of `npm run check`, because it needs a real key
|
|
156
|
+
and real account state. Run it after any change to how a tool reads an API response.
|
|
157
|
+
|
|
158
|
+
It exists because the test suite structurally cannot catch a wrong response shape: the
|
|
159
|
+
tests inject `fetch`, so they prove the tools behave correctly _given_ a shape, never
|
|
160
|
+
that the shape is the one the API sends. The stubs were written from the same reading of
|
|
161
|
+
the API as the code, so both were wrong in the same way and 79 tests stayed green.
|
|
162
|
+
|
|
163
|
+
The first live run found that `analyze` — the primary tool — returned **no findings at
|
|
164
|
+
all**. It read `job.reportId`; the API puts findings at `job.result.analysis` and the id
|
|
165
|
+
at `job.result.reportId`. It also found that `summary.critical`/`.high`/`.medium` count
|
|
166
|
+
checks _by severity including the ones that passed_ (88 on a document with 7 failures),
|
|
167
|
+
so reporting them as issue counts would have shown users failures that did not exist.
|
|
168
|
+
|
|
169
|
+
`verify:live` submits nothing billable except through `remediate`, which it only lists.
|
|
170
|
+
Point it at a local stack or a disposable account.
|
|
171
|
+
|
|
172
|
+
`npm run smoke` is separate from the tests on purpose. The tests reach the server
|
|
173
|
+
through an in-memory transport, which never launches the binary and never notices a
|
|
174
|
+
stray write to **stdout** — and stdout _is_ the transport, so one stray line corrupts
|
|
175
|
+
the JSON-RPC stream while every test still passes.
|
|
176
|
+
|
|
177
|
+
### Hooks
|
|
178
|
+
|
|
179
|
+
Installed by `npm run hooks:install`, once per clone.
|
|
180
|
+
|
|
181
|
+
Deliberately **not** a `prepare` script, which is how the application repos in this
|
|
182
|
+
estate do it. `prepare` runs on `npm ci --omit=dev` too, where husky is not installed, so
|
|
183
|
+
the install fails with `command failed: sh -c husky` — the break that once shipped a
|
|
184
|
+
sibling's production image undeployable. `@honu-office/sdk`, the other published package
|
|
185
|
+
here, avoids it the same way.
|
|
186
|
+
|
|
187
|
+
- **commit-msg** — commitlint, conventional commits.
|
|
188
|
+
- **pre-commit** — secret scan of the _staged_ content, copied out of the index. Not
|
|
189
|
+
`--since-commit HEAD`, which scans nothing at commit time, and not `.`, which would
|
|
190
|
+
walk `node_modules` and flag untracked files.
|
|
191
|
+
- **pre-push** — secret scan of committed history, then `npm run check`. It uses
|
|
192
|
+
`scripts/scan-history-secrets.sh`, shared verbatim with officea11y-api and
|
|
193
|
+
officea11y-fs-crawler: it pins each pushed commit under a temporary ref first, because
|
|
194
|
+
a clone carries refs and a commit on a detached HEAD would otherwise never be scanned.
|
|
195
|
+
|
|
196
|
+
Both scans soft-skip when trufflehog is absent and say so.
|
|
197
|
+
|
|
198
|
+
The server talks to the REST API directly rather than through `@honu-office/sdk`, because
|
|
199
|
+
that package is not published yet — depending on it would make this server uninstallable.
|
|
200
|
+
All HTTP lives in `src/http.js`, so switching to the SDK later is a change to one file.
|
|
201
|
+
|
|
202
|
+
## License
|
|
203
|
+
|
|
204
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,60 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@honu-office/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "MCP server for HonuOffice — analyze, convert, discover and remediate documents from an agent",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"private": false,
|
|
8
|
+
"bin": {
|
|
9
|
+
"honu-office-mcp": "src/index.js"
|
|
10
|
+
},
|
|
11
|
+
"main": "src/index.js",
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=22.0.0"
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"src/",
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"start": "node src/index.js",
|
|
22
|
+
"test": "node --test test/*.test.js",
|
|
23
|
+
"test:coverage": "node --test --experimental-test-coverage test/*.test.js",
|
|
24
|
+
"smoke": "node scripts/smoke-stdio.mjs",
|
|
25
|
+
"security:audit": "npm audit --omit=dev --audit-level=high",
|
|
26
|
+
"security:audit:dev": "npm audit --audit-level=high",
|
|
27
|
+
"security:secrets": "sh scripts/scan-history-secrets.sh",
|
|
28
|
+
"lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"",
|
|
29
|
+
"check": "npm run lint:md && npm test && npm run smoke",
|
|
30
|
+
"hooks:install": "husky",
|
|
31
|
+
"verify:live": "node scripts/verify-live.mjs"
|
|
32
|
+
},
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
35
|
+
"zod": "4.6.7"
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {
|
|
38
|
+
"@commitlint/cli": "^21.2.3",
|
|
39
|
+
"@commitlint/config-conventional": "^21.2.3",
|
|
40
|
+
"husky": "^9.1.7",
|
|
41
|
+
"markdownlint-cli2": "0.24.0"
|
|
42
|
+
},
|
|
43
|
+
"keywords": [
|
|
44
|
+
"mcp",
|
|
45
|
+
"model-context-protocol",
|
|
46
|
+
"accessibility",
|
|
47
|
+
"a11y",
|
|
48
|
+
"pdf",
|
|
49
|
+
"pdf-ua",
|
|
50
|
+
"wcag",
|
|
51
|
+
"honu-office"
|
|
52
|
+
],
|
|
53
|
+
"repository": {
|
|
54
|
+
"type": "git",
|
|
55
|
+
"url": "git+https://github.com/AFixt/honu-office-mcp.git"
|
|
56
|
+
},
|
|
57
|
+
"overrides": {
|
|
58
|
+
"katex": "^0.18.2"
|
|
59
|
+
}
|
|
60
|
+
}
|
package/src/config.js
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Configuration, read from the environment.
|
|
3
|
+
*
|
|
4
|
+
* An MCP server is launched by the client (Claude Desktop, say) from a JSON
|
|
5
|
+
* config block, so the environment is the only channel there is. Nothing here
|
|
6
|
+
* is read at import time: `loadConfig()` is called when a tool runs, so a
|
|
7
|
+
* missing key produces a tool error the user can read rather than a server
|
|
8
|
+
* that dies on startup and shows up as "disconnected" with no reason given.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/** Where the API lives when nothing says otherwise. */
|
|
12
|
+
export const DEFAULT_BASE_URL = 'https://officea11y.com';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* How long a tool waits for an asynchronous job before giving up and handing
|
|
16
|
+
* back the id. Analysis of a large PDF is measured in tens of seconds, so a
|
|
17
|
+
* short ceiling would turn every real document into a timeout.
|
|
18
|
+
*
|
|
19
|
+
* This is the budget for the WHOLE poll loop, not for one HTTP request. The two
|
|
20
|
+
* are separate on purpose: see DEFAULT_REQUEST_TIMEOUT_MS.
|
|
21
|
+
*/
|
|
22
|
+
export const DEFAULT_TIMEOUT_MS = 180_000;
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* How long any single HTTP request may take before it is aborted.
|
|
26
|
+
*
|
|
27
|
+
* Node's fetch will not do this for us: a server that accepts the connection
|
|
28
|
+
* and then says nothing leaves the request outstanding indefinitely -- measured
|
|
29
|
+
* at over 25 seconds with no sign of stopping. For an MCP server that is worse
|
|
30
|
+
* than an error, because the agent simply waits and the user sees the client
|
|
31
|
+
* hang with nothing to act on.
|
|
32
|
+
*
|
|
33
|
+
* A status poll should answer in well under a second, so 60s is generous.
|
|
34
|
+
*/
|
|
35
|
+
export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* The same ceiling for uploads, which legitimately take longer: a large
|
|
39
|
+
* document on a slow link is a real case, and killing it at 60s would break
|
|
40
|
+
* ordinary use rather than protect it.
|
|
41
|
+
*/
|
|
42
|
+
export const DEFAULT_UPLOAD_TIMEOUT_MS = 300_000;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The prefix the environment variables carry.
|
|
46
|
+
*
|
|
47
|
+
* It was OFFICEA11Y_ before the product became Honu Office (OA-349). Those
|
|
48
|
+
* names are not ours to change: they live in the user's MCP client
|
|
49
|
+
* configuration -- the "env" block of claude_desktop_config.json and its
|
|
50
|
+
* equivalents -- which this package cannot edit. So both prefixes are read,
|
|
51
|
+
* the new one wins, and a value that arrived under the old name is reported
|
|
52
|
+
* once rather than silently accepted or silently dropped.
|
|
53
|
+
*/
|
|
54
|
+
const PREFIX = 'HONU_OFFICE_';
|
|
55
|
+
|
|
56
|
+
/** The prefix used before the rename. Still read; reported as deprecated. */
|
|
57
|
+
const LEGACY_PREFIX = 'OFFICEA11Y_';
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Legacy names already reported in this process.
|
|
61
|
+
*
|
|
62
|
+
* loadConfig() runs per tool invocation, not at startup -- see the note at the
|
|
63
|
+
* top of this file -- so a warning emitted inside it repeats for every analyze,
|
|
64
|
+
* convert, discover and remediate call. Measured before this set existed: four
|
|
65
|
+
* calls produced four identical lines, and a long session produces one per
|
|
66
|
+
* tool use indefinitely. The point of the warning is to be read once, so each
|
|
67
|
+
* distinct name is reported once per process and then kept quiet.
|
|
68
|
+
*/
|
|
69
|
+
const reportedLegacyNames = new Set();
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Read one setting, preferring the current name over the pre-rename one.
|
|
73
|
+
*
|
|
74
|
+
* A name set to whitespace counts as unset, matching how every caller treats
|
|
75
|
+
* these values, so a blank new-style variable does not mask a real old-style
|
|
76
|
+
* one.
|
|
77
|
+
*
|
|
78
|
+
* Also reports WHICH name supplied the value, so an error about a bad value
|
|
79
|
+
* can name the variable the user actually set. Naming the new one at someone
|
|
80
|
+
* who set the old one sends them looking for something they never wrote.
|
|
81
|
+
*
|
|
82
|
+
* @param {NodeJS.ProcessEnv} env - The environment to read.
|
|
83
|
+
* @param {string} suffix - The part after the prefix, e.g. 'API_KEY'.
|
|
84
|
+
* @param {string[]} deprecated - Collects the old names that were used.
|
|
85
|
+
* @returns {{value: string, name: string}} The raw value (or '') and the
|
|
86
|
+
* variable it came from, defaulting to the current name when unset.
|
|
87
|
+
*/
|
|
88
|
+
function readPrefixed(env, suffix, deprecated) {
|
|
89
|
+
const current = (env[PREFIX + suffix] || '').trim();
|
|
90
|
+
if (current) {
|
|
91
|
+
return { value: current, name: PREFIX + suffix };
|
|
92
|
+
}
|
|
93
|
+
const legacy = (env[LEGACY_PREFIX + suffix] || '').trim();
|
|
94
|
+
if (legacy) {
|
|
95
|
+
deprecated.push(`${LEGACY_PREFIX}${suffix} (use ${PREFIX}${suffix})`);
|
|
96
|
+
return { value: legacy, name: LEGACY_PREFIX + suffix };
|
|
97
|
+
}
|
|
98
|
+
return { value: '', name: PREFIX + suffix };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Raised when the server is not configured well enough to call the API. */
|
|
102
|
+
export class ConfigError extends Error {
|
|
103
|
+
/** @param {string} message - What is wrong and how to fix it. */
|
|
104
|
+
constructor(message) {
|
|
105
|
+
super(message);
|
|
106
|
+
this.name = 'ConfigError';
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Read and validate the environment.
|
|
112
|
+
*
|
|
113
|
+
* @param {NodeJS.ProcessEnv} [env] - Defaults to `process.env`; injectable for tests.
|
|
114
|
+
* @param {{warn?: (message: string) => void, seen?: Set<string>}} [options] -
|
|
115
|
+
* `warn` defaults to a line on stderr. It must not be stdout: that carries
|
|
116
|
+
* the MCP protocol. `seen` is the set of legacy names already reported,
|
|
117
|
+
* defaulting to one shared across the process so each is said once; pass a
|
|
118
|
+
* fresh Set to read the notice as a first-time caller would.
|
|
119
|
+
* @returns {{apiKey: string, baseUrl: string, timeoutMs: number}} The resolved configuration.
|
|
120
|
+
* @throws {ConfigError} When the API key is absent, or a supplied value is unusable.
|
|
121
|
+
*/
|
|
122
|
+
export function loadConfig(env = process.env, options = {}) {
|
|
123
|
+
const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
|
|
124
|
+
const seen = options.seen ?? reportedLegacyNames;
|
|
125
|
+
const deprecated = [];
|
|
126
|
+
|
|
127
|
+
const { value: apiKey } = readPrefixed(env, 'API_KEY', deprecated);
|
|
128
|
+
if (!apiKey) {
|
|
129
|
+
throw new ConfigError(
|
|
130
|
+
`${PREFIX}API_KEY is not set. Create an API key in your Honu Office account ` +
|
|
131
|
+
'(Account -> API keys) and add it to this server\'s "env" block in your MCP ' +
|
|
132
|
+
`client configuration. See the README for the exact block. The former name, ` +
|
|
133
|
+
`${LEGACY_PREFIX}API_KEY, is still read.`
|
|
134
|
+
);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const base = readPrefixed(env, 'BASE_URL', deprecated);
|
|
138
|
+
const rawBase = base.value || DEFAULT_BASE_URL;
|
|
139
|
+
let baseUrl;
|
|
140
|
+
try {
|
|
141
|
+
// Reject a malformed base URL here rather than letting every request fail
|
|
142
|
+
// with a confusing parse error at the point of use.
|
|
143
|
+
const parsed = new URL(rawBase);
|
|
144
|
+
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
|
|
145
|
+
throw new Error(`unsupported protocol ${parsed.protocol}`);
|
|
146
|
+
}
|
|
147
|
+
baseUrl = parsed.origin;
|
|
148
|
+
} catch (error) {
|
|
149
|
+
throw new ConfigError(
|
|
150
|
+
`${base.name} is not a usable URL (${rawBase}): ${error.message}. ` +
|
|
151
|
+
`Leave it unset to use ${DEFAULT_BASE_URL}.`
|
|
152
|
+
);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
const timeout = readPrefixed(env, 'TIMEOUT_MS', deprecated);
|
|
156
|
+
const rawTimeout = timeout.value;
|
|
157
|
+
let timeoutMs = DEFAULT_TIMEOUT_MS;
|
|
158
|
+
if (rawTimeout) {
|
|
159
|
+
const parsed = Number(rawTimeout);
|
|
160
|
+
if (!Number.isFinite(parsed) || parsed <= 0) {
|
|
161
|
+
throw new ConfigError(
|
|
162
|
+
`${timeout.name} must be a positive number of milliseconds, got "${rawTimeout}".`
|
|
163
|
+
);
|
|
164
|
+
}
|
|
165
|
+
timeoutMs = parsed;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
const config = {
|
|
169
|
+
apiKey,
|
|
170
|
+
baseUrl,
|
|
171
|
+
timeoutMs,
|
|
172
|
+
requestTimeoutMs: readPositiveMs(env, 'REQUEST_TIMEOUT_MS', DEFAULT_REQUEST_TIMEOUT_MS, deprecated),
|
|
173
|
+
uploadTimeoutMs: readPositiveMs(env, 'UPLOAD_TIMEOUT_MS', DEFAULT_UPLOAD_TIMEOUT_MS, deprecated),
|
|
174
|
+
};
|
|
175
|
+
|
|
176
|
+
// Said once, after everything is read, so a user renaming several variables
|
|
177
|
+
// sees one line listing all of them rather than a warning per lookup -- and
|
|
178
|
+
// once per process rather than once per tool call, since this function runs
|
|
179
|
+
// on every invocation.
|
|
180
|
+
const unreported = deprecated.filter((name) => !seen.has(name));
|
|
181
|
+
if (unreported.length > 0) {
|
|
182
|
+
for (const name of unreported) {
|
|
183
|
+
seen.add(name);
|
|
184
|
+
}
|
|
185
|
+
warn(
|
|
186
|
+
`honu-office-mcp: these environment variable names were renamed and will ` +
|
|
187
|
+
`stop being read in a future release: ${unreported.join(', ')}.`
|
|
188
|
+
);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
return config;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* Read a millisecond value, falling back to a default.
|
|
196
|
+
*
|
|
197
|
+
* @param {NodeJS.ProcessEnv} env - Environment to read.
|
|
198
|
+
* @param {string} suffix - The part after the prefix, e.g. 'REQUEST_TIMEOUT_MS'.
|
|
199
|
+
* @param {number} fallback - Default when unset.
|
|
200
|
+
* @param {string[]} deprecated - Collects the old names that were used.
|
|
201
|
+
* @returns {number} The value.
|
|
202
|
+
* @throws {ConfigError} When set to something that is not a positive number.
|
|
203
|
+
*/
|
|
204
|
+
function readPositiveMs(env, suffix, fallback, deprecated) {
|
|
205
|
+
const { value: raw, name } = readPrefixed(env, suffix, deprecated);
|
|
206
|
+
if (!raw) return fallback;
|
|
207
|
+
const parsed = Number(raw);
|
|
208
|
+
if (!Number.isFinite(parsed) || parsed <= 0) {
|
|
209
|
+
throw new ConfigError(
|
|
210
|
+
`${name} must be a positive number of milliseconds, got "${raw}".`
|
|
211
|
+
);
|
|
212
|
+
}
|
|
213
|
+
return parsed;
|
|
214
|
+
}
|
package/src/files.js
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading the local files a tool was pointed at.
|
|
3
|
+
*
|
|
4
|
+
* This server runs on the user's machine, which is the whole reason it can take
|
|
5
|
+
* a path at all: the alternative would be making someone host a document
|
|
6
|
+
* publicly before they can ask whether it is accessible.
|
|
7
|
+
*
|
|
8
|
+
* That also means the paths come from a model, so they get checked rather than
|
|
9
|
+
* trusted. A clear refusal beats a stack trace, and beats uploading something
|
|
10
|
+
* the user did not mean to send.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { readFile, stat } from 'node:fs/promises';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
|
|
16
|
+
/** Formats HonuOffice accepts for analysis or conversion. */
|
|
17
|
+
export const SUPPORTED_EXTENSIONS = new Set([
|
|
18
|
+
'.pdf',
|
|
19
|
+
'.docx',
|
|
20
|
+
'.doc',
|
|
21
|
+
'.xlsx',
|
|
22
|
+
'.xls',
|
|
23
|
+
'.pptx',
|
|
24
|
+
'.ppt',
|
|
25
|
+
'.html',
|
|
26
|
+
'.htm',
|
|
27
|
+
]);
|
|
28
|
+
|
|
29
|
+
/** Raised when a path cannot be used. The message says why. */
|
|
30
|
+
export class FileError extends Error {
|
|
31
|
+
/** @param {string} message - What is wrong with the path. */
|
|
32
|
+
constructor(message) {
|
|
33
|
+
super(message);
|
|
34
|
+
this.name = 'FileError';
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Read a document from disk, with the checks worth doing before an upload.
|
|
40
|
+
*
|
|
41
|
+
* @param {string} filePath - Absolute or relative path to the document.
|
|
42
|
+
* @param {{maxBytes?: number, allowAnyExtension?: boolean}} [options] - Read options.
|
|
43
|
+
* @returns {Promise<{buffer: Buffer, filename: string, path: string, size: number}>} The file.
|
|
44
|
+
* @throws {FileError} When the path is missing, is not a file, is empty, is too
|
|
45
|
+
* large, or has an extension HonuOffice does not handle.
|
|
46
|
+
*/
|
|
47
|
+
export async function readDocument(filePath, options = {}) {
|
|
48
|
+
const maxBytes = options.maxBytes ?? 100 * 1024 * 1024;
|
|
49
|
+
|
|
50
|
+
if (typeof filePath !== 'string' || filePath.trim() === '') {
|
|
51
|
+
throw new FileError('No file path was given.');
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const resolved = path.resolve(filePath);
|
|
55
|
+
|
|
56
|
+
let info;
|
|
57
|
+
try {
|
|
58
|
+
info = await stat(resolved);
|
|
59
|
+
} catch (error) {
|
|
60
|
+
if (error.code === 'ENOENT') {
|
|
61
|
+
throw new FileError(`No file at ${resolved}. Give an absolute path, or one relative to where this server was started.`);
|
|
62
|
+
}
|
|
63
|
+
if (error.code === 'EACCES') {
|
|
64
|
+
throw new FileError(`Not permitted to read ${resolved}.`);
|
|
65
|
+
}
|
|
66
|
+
throw new FileError(`Could not read ${resolved}: ${error.message}`);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
if (info.isDirectory()) {
|
|
70
|
+
throw new FileError(`${resolved} is a directory, not a document.`);
|
|
71
|
+
}
|
|
72
|
+
if (!info.isFile()) {
|
|
73
|
+
throw new FileError(`${resolved} is not a regular file.`);
|
|
74
|
+
}
|
|
75
|
+
if (info.size === 0) {
|
|
76
|
+
// An empty file uploads fine and comes back with a baffling analysis
|
|
77
|
+
// failure, so it is worth catching here where the cause is obvious.
|
|
78
|
+
throw new FileError(`${resolved} is empty.`);
|
|
79
|
+
}
|
|
80
|
+
if (info.size > maxBytes) {
|
|
81
|
+
throw new FileError(
|
|
82
|
+
`${resolved} is ${formatBytes(info.size)}, over the ${formatBytes(maxBytes)} limit.`
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const extension = path.extname(resolved).toLowerCase();
|
|
87
|
+
if (!options.allowAnyExtension && !SUPPORTED_EXTENSIONS.has(extension)) {
|
|
88
|
+
throw new FileError(
|
|
89
|
+
`${resolved} has an unsupported extension (${extension || 'none'}). ` +
|
|
90
|
+
`Supported: ${[...SUPPORTED_EXTENSIONS].join(', ')}.`
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const buffer = await readFile(resolved);
|
|
95
|
+
return { buffer, filename: path.basename(resolved), path: resolved, size: info.size };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Render a byte count the way a person would say it.
|
|
100
|
+
*
|
|
101
|
+
* @param {number} bytes - The count.
|
|
102
|
+
* @returns {string} e.g. "2.4 MB".
|
|
103
|
+
*/
|
|
104
|
+
export function formatBytes(bytes) {
|
|
105
|
+
if (bytes < 1024) return `${bytes} B`;
|
|
106
|
+
if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
|
|
107
|
+
return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
|
|
108
|
+
}
|