justfill-mcp 0.0.0-stage → 0.1.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 +113 -2
- package/bin/justfill-mcp.mjs +418 -0
- package/package.json +44 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 JustFill
|
|
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,114 @@
|
|
|
1
|
-
#
|
|
1
|
+
# justfill-mcp (npm)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Zero-dependency Node.js (`npx -y justfill-mcp`) bridge for the hosted [JustFill PDF Forms MCP Server](https://justfill.app/mcp) (`https://justfill.app/api/mcp`).
|
|
4
|
+
|
|
5
|
+
Let AI agents in **Cursor, Windsurf, VS Code, Claude Desktop, and Claude Code** detect fields on flat, scanned, or AcroForm PDFs, visually preview filled pages, export clean PDFs, and save reusable templates — without needing Python or `uvx`.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
### 1. Authorize once (opens your browser, no password in config files)
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx -y justfill-mcp login
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
This saves a revocable API key to `~/.config/justfill/credentials.json` (mode `0600`) — shared automatically with the Python `uvx justfill-mcp` client too.
|
|
16
|
+
|
|
17
|
+
Alternatively, create an API key in [justfill.app → Account → API Keys](https://justfill.app/account) and pass `JUSTFILL_API_KEY`.
|
|
18
|
+
|
|
19
|
+
### 2. Add to your MCP client
|
|
20
|
+
|
|
21
|
+
#### Cursor (`.cursor/mcp.json`)
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"mcpServers": {
|
|
26
|
+
"justfill": {
|
|
27
|
+
"command": "npx",
|
|
28
|
+
"args": ["-y", "justfill-mcp"]
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
> Cursor also supports connecting directly to the hosted Remote MCP URL without stdio:
|
|
35
|
+
> ```json
|
|
36
|
+
> {
|
|
37
|
+
> "mcpServers": {
|
|
38
|
+
> "justfill": {
|
|
39
|
+
> "url": "https://justfill.app/api/mcp"
|
|
40
|
+
> }
|
|
41
|
+
> }
|
|
42
|
+
> }
|
|
43
|
+
> ```
|
|
44
|
+
|
|
45
|
+
#### Claude Desktop (`claude_desktop_config.json`)
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"mcpServers": {
|
|
50
|
+
"justfill": {
|
|
51
|
+
"command": "npx",
|
|
52
|
+
"args": ["-y", "justfill-mcp"]
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
#### Claude Code
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
claude mcp add justfill -- npx -y justfill-mcp
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Or connect directly via Streamable HTTP + OAuth:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
claude mcp add --transport http justfill https://justfill.app/api/mcp
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
#### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"justfill": {
|
|
76
|
+
"command": "npx",
|
|
77
|
+
"args": ["-y", "justfill-mcp"]
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
#### VS Code (`.vscode/mcp.json`)
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"servers": {
|
|
88
|
+
"justfill": {
|
|
89
|
+
"type": "stdio",
|
|
90
|
+
"command": "npx",
|
|
91
|
+
"args": ["-y", "justfill-mcp"]
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Batch PDF Filling (Excel / CSV & REST API)
|
|
98
|
+
|
|
99
|
+
Need to fill the same PDF template for 10–2,500 rows from Excel or CSV?
|
|
100
|
+
|
|
101
|
+
- **Browser Batch Mode**: [https://justfill.app/editor?mode=batch](https://justfill.app/editor?mode=batch) (5-row watermarked sample free)
|
|
102
|
+
- **REST API**: `POST https://justfill.app/api/v1/batch-fill` (ZIP or JSON/base64, ideal for Zapier, Make.com, and n8n)
|
|
103
|
+
|
|
104
|
+
## CLI Options & Environment Variables
|
|
105
|
+
|
|
106
|
+
| Option / Env | Default | Description |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| `--url` / `JUSTFILL_MCP_URL` | `https://justfill.app/api/mcp` | Remote Streamable HTTP MCP endpoint |
|
|
109
|
+
| `--api-key` / `JUSTFILL_API_KEY` | `~/.config/justfill/credentials.json` | JustFill Bearer API key (`jf_live_...`) |
|
|
110
|
+
| `--app-url` / `JUSTFILL_APP_URL` | `https://justfill.app` | Web origin used during `justfill-mcp login` |
|
|
111
|
+
|
|
112
|
+
## License
|
|
113
|
+
|
|
114
|
+
MIT — see [LICENSE](./LICENSE).
|
|
@@ -0,0 +1,418 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* justfill-mcp — zero-dependency Node.js stdio <-> Streamable HTTP MCP bridge
|
|
4
|
+
* for JustFill PDF Forms (https://justfill.app/api/mcp).
|
|
5
|
+
*
|
|
6
|
+
* Works with Cursor, Windsurf, VS Code, Claude Desktop, and Claude Code via:
|
|
7
|
+
* npx -y justfill-mcp
|
|
8
|
+
*
|
|
9
|
+
* Auth resolution order:
|
|
10
|
+
* 1. --api-key <jf_live_...>
|
|
11
|
+
* 2. JUSTFILL_API_KEY environment variable
|
|
12
|
+
* 3. ~/.config/justfill/credentials.json (created by `npx -y justfill-mcp login`
|
|
13
|
+
* or `uvx justfill-mcp login`)
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import { spawn } from 'node:child_process';
|
|
17
|
+
import crypto from 'node:crypto';
|
|
18
|
+
import fs from 'node:fs';
|
|
19
|
+
import http from 'node:http';
|
|
20
|
+
import os from 'node:os';
|
|
21
|
+
import path from 'node:path';
|
|
22
|
+
import readline from 'node:readline';
|
|
23
|
+
import { fileURLToPath } from 'node:url';
|
|
24
|
+
|
|
25
|
+
export const DEFAULT_MCP_URL = 'https://justfill.app/api/mcp';
|
|
26
|
+
export const DEFAULT_APP_URL = 'https://justfill.app';
|
|
27
|
+
export const PACKAGE_VERSION = '0.1.0';
|
|
28
|
+
const LOGIN_TIMEOUT_MS = 300_000;
|
|
29
|
+
|
|
30
|
+
const DONE_HTML = `<!doctype html><meta charset="utf-8">
|
|
31
|
+
<title>JustFill — authorized</title>
|
|
32
|
+
<body style="font-family:system-ui;display:grid;place-items:center;height:90vh;margin:0">
|
|
33
|
+
<div style="text-align:center">
|
|
34
|
+
<h2>✅ JustFill MCP is authorized</h2>
|
|
35
|
+
<p>You can close this tab and return to your editor or terminal.</p>
|
|
36
|
+
</div></body>`;
|
|
37
|
+
|
|
38
|
+
export function credentialsPath(env = process.env, homeDir = os.homedir()) {
|
|
39
|
+
const base = env.XDG_CONFIG_HOME || path.join(homeDir, '.config');
|
|
40
|
+
return path.join(base, 'justfill', 'credentials.json');
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function loadStoredApiKey(env = process.env, homeDir = os.homedir()) {
|
|
44
|
+
try {
|
|
45
|
+
const raw = fs.readFileSync(credentialsPath(env, homeDir), 'utf8');
|
|
46
|
+
const data = JSON.parse(raw);
|
|
47
|
+
return typeof data?.api_key === 'string' && data.api_key.trim() ? data.api_key.trim() : null;
|
|
48
|
+
} catch {
|
|
49
|
+
return null;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function saveStoredApiKey(apiKey, appUrl = DEFAULT_APP_URL, env = process.env, homeDir = os.homedir()) {
|
|
54
|
+
const target = credentialsPath(env, homeDir);
|
|
55
|
+
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
56
|
+
fs.writeFileSync(
|
|
57
|
+
target,
|
|
58
|
+
JSON.stringify({ api_key: apiKey, app_url: appUrl.replace(/\/+$/, '') }, null, 1),
|
|
59
|
+
{ encoding: 'utf8', mode: 0o600 }
|
|
60
|
+
);
|
|
61
|
+
try {
|
|
62
|
+
fs.chmodSync(target, 0o600);
|
|
63
|
+
} catch {
|
|
64
|
+
// chmod may be a no-op on Windows filesystems.
|
|
65
|
+
}
|
|
66
|
+
return target;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function parseArgs(argv) {
|
|
70
|
+
const opts = {
|
|
71
|
+
command: 'serve',
|
|
72
|
+
help: false,
|
|
73
|
+
version: false,
|
|
74
|
+
url: null,
|
|
75
|
+
appUrl: null,
|
|
76
|
+
apiKey: null,
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
for (let i = 0; i < argv.length; i += 1) {
|
|
80
|
+
const arg = argv[i];
|
|
81
|
+
if (arg === '-h' || arg === '--help') {
|
|
82
|
+
opts.help = true;
|
|
83
|
+
} else if (arg === '-v' || arg === '--version') {
|
|
84
|
+
opts.version = true;
|
|
85
|
+
} else if (arg === 'login' && opts.command === 'serve') {
|
|
86
|
+
opts.command = 'login';
|
|
87
|
+
} else if (arg === '--url' && argv[i + 1]) {
|
|
88
|
+
opts.url = argv[++i];
|
|
89
|
+
} else if (arg.startsWith('--url=')) {
|
|
90
|
+
opts.url = arg.slice('--url='.length);
|
|
91
|
+
} else if (arg === '--app-url' && argv[i + 1]) {
|
|
92
|
+
opts.appUrl = argv[++i];
|
|
93
|
+
} else if (arg.startsWith('--app-url=')) {
|
|
94
|
+
opts.appUrl = arg.slice('--app-url='.length);
|
|
95
|
+
} else if (arg === '--api-key' && argv[i + 1]) {
|
|
96
|
+
opts.apiKey = argv[++i];
|
|
97
|
+
} else if (arg.startsWith('--api-key=')) {
|
|
98
|
+
opts.apiKey = arg.slice('--api-key='.length);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return opts;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
export function resolveApiKey(opts, env = process.env, homeDir = os.homedir()) {
|
|
105
|
+
if (opts?.apiKey && opts.apiKey.trim()) return opts.apiKey.trim();
|
|
106
|
+
if (env.JUSTFILL_API_KEY && env.JUSTFILL_API_KEY.trim()) return env.JUSTFILL_API_KEY.trim();
|
|
107
|
+
return loadStoredApiKey(env, homeDir);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
export function printHelp(stream = process.stdout) {
|
|
111
|
+
stream.write(
|
|
112
|
+
`justfill-mcp v${PACKAGE_VERSION} — JustFill PDF Forms MCP bridge (stdio -> Streamable HTTP)\n\n` +
|
|
113
|
+
`Usage:\n` +
|
|
114
|
+
` npx -y justfill-mcp Start stdio MCP bridge to ${DEFAULT_MCP_URL}\n` +
|
|
115
|
+
` npx -y justfill-mcp login Authorize once in your browser (saves ~/.config/justfill/credentials.json)\n\n` +
|
|
116
|
+
`Options:\n` +
|
|
117
|
+
` --url <url> Remote MCP endpoint (default: $JUSTFILL_MCP_URL or ${DEFAULT_MCP_URL})\n` +
|
|
118
|
+
` --api-key <key> JustFill API key (default: $JUSTFILL_API_KEY or stored credentials)\n` +
|
|
119
|
+
` --app-url <url> JustFill web origin for 'login' (default: $JUSTFILL_APP_URL or ${DEFAULT_APP_URL})\n` +
|
|
120
|
+
` -v, --version Print package version\n` +
|
|
121
|
+
` -h, --help Show this help message\n\n` +
|
|
122
|
+
`Docs & setup guides: https://justfill.app/mcp\n`
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export function parseSseMessages(sseBody) {
|
|
127
|
+
const messages = [];
|
|
128
|
+
const blocks = sseBody.split(/\r?\n\r?\n/);
|
|
129
|
+
for (const block of blocks) {
|
|
130
|
+
const dataLines = [];
|
|
131
|
+
for (const line of block.split(/\r?\n/)) {
|
|
132
|
+
if (line.startsWith('data:')) {
|
|
133
|
+
dataLines.push(line.slice(5).trimStart());
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
if (dataLines.length === 0) continue;
|
|
137
|
+
const payload = dataLines.join('\n').trim();
|
|
138
|
+
if (!payload || payload === '[DONE]') continue;
|
|
139
|
+
try {
|
|
140
|
+
messages.push(JSON.parse(payload));
|
|
141
|
+
} catch {
|
|
142
|
+
// Ignore non-JSON SSE control frames.
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return messages;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function openBrowser(url) {
|
|
149
|
+
let cmd;
|
|
150
|
+
let args;
|
|
151
|
+
if (process.platform === 'darwin') {
|
|
152
|
+
cmd = 'open';
|
|
153
|
+
args = [url];
|
|
154
|
+
} else if (process.platform === 'win32') {
|
|
155
|
+
cmd = 'cmd';
|
|
156
|
+
args = ['/c', 'start', '', url];
|
|
157
|
+
} else {
|
|
158
|
+
cmd = 'xdg-open';
|
|
159
|
+
args = [url];
|
|
160
|
+
}
|
|
161
|
+
try {
|
|
162
|
+
const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
|
|
163
|
+
child.on('error', () => {});
|
|
164
|
+
child.unref();
|
|
165
|
+
} catch {
|
|
166
|
+
// Non-fatal: URL is always printed to stdout.
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
function timingSafeEqualStr(a, b) {
|
|
171
|
+
const bufA = Buffer.from(String(a || ''), 'utf8');
|
|
172
|
+
const bufB = Buffer.from(String(b || ''), 'utf8');
|
|
173
|
+
if (bufA.length !== bufB.length) return false;
|
|
174
|
+
return crypto.timingSafeEqual(bufA, bufB);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
export async function runLogin(opts, env = process.env, homeDir = os.homedir()) {
|
|
178
|
+
const appUrl = (opts.appUrl || env.JUSTFILL_APP_URL || DEFAULT_APP_URL).replace(/\/+$/, '');
|
|
179
|
+
const nonce = crypto.randomBytes(16).toString('base64url');
|
|
180
|
+
|
|
181
|
+
return new Promise((resolve) => {
|
|
182
|
+
let settled = false;
|
|
183
|
+
let timer;
|
|
184
|
+
|
|
185
|
+
const finish = (code) => {
|
|
186
|
+
if (settled) return;
|
|
187
|
+
settled = true;
|
|
188
|
+
clearTimeout(timer);
|
|
189
|
+
server.close(() => resolve(code));
|
|
190
|
+
};
|
|
191
|
+
|
|
192
|
+
const server = http.createServer((req, res) => {
|
|
193
|
+
const reqUrl = new URL(req.url || '/', 'http://127.0.0.1');
|
|
194
|
+
if (reqUrl.pathname !== '/callback') {
|
|
195
|
+
res.writeHead(404);
|
|
196
|
+
res.end();
|
|
197
|
+
return;
|
|
198
|
+
}
|
|
199
|
+
const key = reqUrl.searchParams.get('key') || '';
|
|
200
|
+
const state = reqUrl.searchParams.get('state') || '';
|
|
201
|
+
if (!timingSafeEqualStr(state, nonce)) {
|
|
202
|
+
res.writeHead(403);
|
|
203
|
+
res.end();
|
|
204
|
+
return;
|
|
205
|
+
}
|
|
206
|
+
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
|
|
207
|
+
res.end(DONE_HTML);
|
|
208
|
+
|
|
209
|
+
if (!key.startsWith('jf_')) {
|
|
210
|
+
process.stderr.write('No valid JustFill API key was received.\n');
|
|
211
|
+
finish(1);
|
|
212
|
+
return;
|
|
213
|
+
}
|
|
214
|
+
const saved = saveStoredApiKey(key, appUrl, env, homeDir);
|
|
215
|
+
process.stdout.write(`Authorized. API key saved to ${saved}\n`);
|
|
216
|
+
process.stdout.write('justfill-mcp will use it automatically — no env vars needed.\n');
|
|
217
|
+
finish(0);
|
|
218
|
+
});
|
|
219
|
+
|
|
220
|
+
server.listen(0, '127.0.0.1', () => {
|
|
221
|
+
const addr = server.address();
|
|
222
|
+
const port = typeof addr === 'object' && addr ? addr.port : 0;
|
|
223
|
+
const clientName = encodeURIComponent(`MCP on ${os.hostname() || 'this computer'}`);
|
|
224
|
+
const authorizeUrl = `${appUrl}/authorize?port=${port}&state=${encodeURIComponent(nonce)}&name=${clientName}`;
|
|
225
|
+
process.stdout.write('Opening your browser to authorize JustFill MCP…\n');
|
|
226
|
+
process.stdout.write(`If it does not open, visit:\n ${authorizeUrl}\n\n`);
|
|
227
|
+
openBrowser(authorizeUrl);
|
|
228
|
+
});
|
|
229
|
+
|
|
230
|
+
timer = setTimeout(() => {
|
|
231
|
+
process.stderr.write('Authorization timed out.\n');
|
|
232
|
+
process.stderr.write(
|
|
233
|
+
`You can also create an API key at ${appUrl}/account and set JUSTFILL_API_KEY.\n`
|
|
234
|
+
);
|
|
235
|
+
finish(1);
|
|
236
|
+
}, LOGIN_TIMEOUT_MS);
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
export async function forwardJsonRpcMessage(message, state, fetchImpl = globalThis.fetch) {
|
|
241
|
+
const isNotification = message.id === undefined || message.id === null;
|
|
242
|
+
const apiKey = state.getApiKey();
|
|
243
|
+
|
|
244
|
+
if (!apiKey) {
|
|
245
|
+
if (isNotification) return [];
|
|
246
|
+
return [
|
|
247
|
+
{
|
|
248
|
+
jsonrpc: '2.0',
|
|
249
|
+
id: message.id,
|
|
250
|
+
error: {
|
|
251
|
+
code: -32001,
|
|
252
|
+
message:
|
|
253
|
+
'JustFill MCP is not authenticated. Run `npx -y justfill-mcp login` once in your terminal ' +
|
|
254
|
+
'or set JUSTFILL_API_KEY (create a key at https://justfill.app/account).',
|
|
255
|
+
},
|
|
256
|
+
},
|
|
257
|
+
];
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
const headers = {
|
|
261
|
+
'Content-Type': 'application/json',
|
|
262
|
+
Accept: 'application/json, text/event-stream',
|
|
263
|
+
Authorization: `Bearer ${apiKey}`,
|
|
264
|
+
'User-Agent': `justfill-mcp-npm/${PACKAGE_VERSION}`,
|
|
265
|
+
};
|
|
266
|
+
if (state.protocolVersion) {
|
|
267
|
+
headers['MCP-Protocol-Version'] = state.protocolVersion;
|
|
268
|
+
}
|
|
269
|
+
if (state.sessionId) {
|
|
270
|
+
headers['Mcp-Session-Id'] = state.sessionId;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
let response;
|
|
274
|
+
try {
|
|
275
|
+
response = await fetchImpl(state.endpoint, {
|
|
276
|
+
method: 'POST',
|
|
277
|
+
headers,
|
|
278
|
+
body: JSON.stringify(message),
|
|
279
|
+
});
|
|
280
|
+
} catch (err) {
|
|
281
|
+
if (isNotification) return [];
|
|
282
|
+
return [
|
|
283
|
+
{
|
|
284
|
+
jsonrpc: '2.0',
|
|
285
|
+
id: message.id,
|
|
286
|
+
error: {
|
|
287
|
+
code: -32000,
|
|
288
|
+
message: `Failed to reach JustFill MCP (${state.endpoint}): ${err?.message || String(err)}`,
|
|
289
|
+
},
|
|
290
|
+
},
|
|
291
|
+
];
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
const nextSessionId = response.headers.get('mcp-session-id');
|
|
295
|
+
if (nextSessionId) {
|
|
296
|
+
state.sessionId = nextSessionId;
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
if (response.status === 202 || response.status === 204) {
|
|
300
|
+
return [];
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
if (response.status === 401 || response.status === 403) {
|
|
304
|
+
if (isNotification) return [];
|
|
305
|
+
return [
|
|
306
|
+
{
|
|
307
|
+
jsonrpc: '2.0',
|
|
308
|
+
id: message.id,
|
|
309
|
+
error: {
|
|
310
|
+
code: -32001,
|
|
311
|
+
message:
|
|
312
|
+
`JustFill MCP rejected authentication (HTTP ${response.status}). ` +
|
|
313
|
+
'Run `npx -y justfill-mcp login` to refresh your key or verify JUSTFILL_API_KEY at https://justfill.app/account.',
|
|
314
|
+
},
|
|
315
|
+
},
|
|
316
|
+
];
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
const contentType = (response.headers.get('content-type') || '').toLowerCase();
|
|
320
|
+
const bodyText = await response.text();
|
|
321
|
+
|
|
322
|
+
if (!response.ok) {
|
|
323
|
+
if (isNotification) return [];
|
|
324
|
+
return [
|
|
325
|
+
{
|
|
326
|
+
jsonrpc: '2.0',
|
|
327
|
+
id: message.id,
|
|
328
|
+
error: {
|
|
329
|
+
code: -32000,
|
|
330
|
+
message: `JustFill MCP returned HTTP ${response.status}: ${bodyText.slice(0, 300)}`,
|
|
331
|
+
},
|
|
332
|
+
},
|
|
333
|
+
];
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
if (!bodyText.trim()) {
|
|
337
|
+
return [];
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
let responses = [];
|
|
341
|
+
if (contentType.includes('text/event-stream')) {
|
|
342
|
+
responses = parseSseMessages(bodyText);
|
|
343
|
+
} else {
|
|
344
|
+
const parsed = JSON.parse(bodyText);
|
|
345
|
+
responses = Array.isArray(parsed) ? parsed : [parsed];
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
if (message.method === 'initialize') {
|
|
349
|
+
const initReply = responses.find((r) => r && r.result && typeof r.result.protocolVersion === 'string');
|
|
350
|
+
if (initReply) {
|
|
351
|
+
state.protocolVersion = initReply.result.protocolVersion;
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
return responses;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
export async function runBridge(opts, env = process.env, homeDir = os.homedir()) {
|
|
359
|
+
const endpoint = (opts.url || env.JUSTFILL_MCP_URL || DEFAULT_MCP_URL).trim();
|
|
360
|
+
const state = {
|
|
361
|
+
endpoint,
|
|
362
|
+
protocolVersion: null,
|
|
363
|
+
sessionId: null,
|
|
364
|
+
getApiKey: () => resolveApiKey(opts, env, homeDir),
|
|
365
|
+
};
|
|
366
|
+
|
|
367
|
+
const rl = readline.createInterface({
|
|
368
|
+
input: process.stdin,
|
|
369
|
+
crlfDelay: Infinity,
|
|
370
|
+
});
|
|
371
|
+
|
|
372
|
+
// Process incoming stdio JSON-RPC requests in order so initialize completes first.
|
|
373
|
+
let queue = Promise.resolve();
|
|
374
|
+
rl.on('line', (line) => {
|
|
375
|
+
const trimmed = line.trim();
|
|
376
|
+
if (!trimmed) return;
|
|
377
|
+
queue = queue.then(async () => {
|
|
378
|
+
let msg;
|
|
379
|
+
try {
|
|
380
|
+
msg = JSON.parse(trimmed);
|
|
381
|
+
} catch {
|
|
382
|
+
process.stderr.write('[justfill-mcp] Ignored malformed JSON line on stdin\n');
|
|
383
|
+
return;
|
|
384
|
+
}
|
|
385
|
+
const replies = await forwardJsonRpcMessage(msg, state);
|
|
386
|
+
for (const reply of replies) {
|
|
387
|
+
process.stdout.write(`${JSON.stringify(reply)}\n`);
|
|
388
|
+
}
|
|
389
|
+
});
|
|
390
|
+
});
|
|
391
|
+
|
|
392
|
+
await new Promise((resolve) => {
|
|
393
|
+
rl.once('close', () => {
|
|
394
|
+
queue.finally(resolve);
|
|
395
|
+
});
|
|
396
|
+
});
|
|
397
|
+
return 0;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
const isMain =
|
|
401
|
+
process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
|
|
402
|
+
|
|
403
|
+
if (isMain) {
|
|
404
|
+
const opts = parseArgs(process.argv.slice(2));
|
|
405
|
+
if (opts.help) {
|
|
406
|
+
printHelp();
|
|
407
|
+
process.exit(0);
|
|
408
|
+
}
|
|
409
|
+
if (opts.version) {
|
|
410
|
+
process.stdout.write(`${PACKAGE_VERSION}\n`);
|
|
411
|
+
process.exit(0);
|
|
412
|
+
}
|
|
413
|
+
if (opts.command === 'login') {
|
|
414
|
+
runLogin(opts).then((code) => process.exit(code));
|
|
415
|
+
} else {
|
|
416
|
+
runBridge(opts).then((code) => process.exit(code));
|
|
417
|
+
}
|
|
418
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "justfill-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "JustFill MCP server wrapper (npx -y justfill-mcp) — detect, preview, and fill flat, scanned, or AcroForm PDF forms from Claude, Cursor, Windsurf, and VS Code.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "JustFill <hello@justfill.app>",
|
|
8
|
+
"homepage": "https://justfill.app/mcp",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "https://github.com/mrmaciej1/justfill-mcp.git"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/mrmaciej1/justfill-mcp/issues"
|
|
15
|
+
},
|
|
16
|
+
"bin": {
|
|
17
|
+
"justfill-mcp": "./bin/justfill-mcp.mjs"
|
|
18
|
+
},
|
|
19
|
+
"files": [
|
|
20
|
+
"bin/",
|
|
21
|
+
"README.md",
|
|
22
|
+
"LICENSE"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=18.0.0"
|
|
26
|
+
},
|
|
27
|
+
"keywords": [
|
|
28
|
+
"mcp",
|
|
29
|
+
"model-context-protocol",
|
|
30
|
+
"pdf",
|
|
31
|
+
"pdf-forms",
|
|
32
|
+
"form-filling",
|
|
33
|
+
"acroform",
|
|
34
|
+
"claude",
|
|
35
|
+
"cursor",
|
|
36
|
+
"windsurf",
|
|
37
|
+
"vscode",
|
|
38
|
+
"chatgpt",
|
|
39
|
+
"ai-agents",
|
|
40
|
+
"justfill"
|
|
41
|
+
],
|
|
42
|
+
"scripts": {
|
|
43
|
+
"test": "node --test test/*.test.mjs"
|
|
44
|
+
},
|
|
45
|
+
"dependencies": {}
|
|
46
|
+
}
|