@plaiful/cli 0.4.0 → 0.6.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/README.md +130 -80
- package/package.json +21 -21
- package/src/cli.js +1120 -970
- package/src/mcp.js +145 -0
package/src/mcp.js
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `plaiful mcp`: an MCP server on stdio (docs/system/product/PLATFORM_DOCS_PORTAL.md §4). It gives a coding assistant
|
|
5
|
+
* (Claude Code, Zed, any MCP client) the live platform docs as tools, signed in as the CLI is (`plaiful login`, or
|
|
6
|
+
* PLAIFUL_TOKEN). Newline-delimited JSON-RPC 2.0 on stdin/stdout; nothing else is written to stdout.
|
|
7
|
+
*
|
|
8
|
+
* claude mcp add plaiful -- plaiful mcp
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
const { version } = require('../package.json');
|
|
12
|
+
|
|
13
|
+
const TOOLS = [
|
|
14
|
+
{
|
|
15
|
+
name: 'list_docs',
|
|
16
|
+
description: 'List the Plaiful platform docs (live): each doc\'s name, title, summary and when it last changed. Read one with read_doc.',
|
|
17
|
+
inputSchema: { type: 'object', properties: {}, additionalProperties: false },
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
name: 'read_doc',
|
|
21
|
+
description: 'Read one Plaiful platform doc, current. Give `section` (a heading, or a number like "3.5") for one section of a long doc.',
|
|
22
|
+
inputSchema: {
|
|
23
|
+
type: 'object',
|
|
24
|
+
properties: {
|
|
25
|
+
doc: { type: 'string', description: 'The doc name from list_docs, e.g. "ovid-client" or "README"' },
|
|
26
|
+
section: { type: 'string', description: 'Optional: a heading or section number' },
|
|
27
|
+
},
|
|
28
|
+
required: ['doc'],
|
|
29
|
+
additionalProperties: false,
|
|
30
|
+
},
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
name: 'search_docs',
|
|
34
|
+
description: 'Search the Plaiful platform docs: the docs and sections that mention every word, best first, with a snippet. Then read_doc with the section.',
|
|
35
|
+
inputSchema: {
|
|
36
|
+
type: 'object',
|
|
37
|
+
properties: { query: { type: 'string' }, limit: { type: 'number', description: 'At most this many docs (default 10)' } },
|
|
38
|
+
required: ['query'],
|
|
39
|
+
additionalProperties: false,
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
name: 'docs_changes',
|
|
44
|
+
description: 'The Plaiful platform docs that changed since a date (default: the last 7 days), newest first.',
|
|
45
|
+
inputSchema: { type: 'object', properties: { since: { type: 'string', description: 'A date, e.g. 2026-10-20' } }, additionalProperties: false },
|
|
46
|
+
},
|
|
47
|
+
];
|
|
48
|
+
|
|
49
|
+
const INSTRUCTIONS = 'Plaiful\'s platform docs, live. Read the relevant doc before working on a Plaiful integration, and again at the start of a task; never rely on a copy. Start with read_doc { doc: "README" }.';
|
|
50
|
+
|
|
51
|
+
const docName = (k) => String(k).replace(/\.md$/, '');
|
|
52
|
+
const route = (rest = '', query = {}) => {
|
|
53
|
+
const qs = new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== null && v !== ''));
|
|
54
|
+
return `/partner/platform/docs${rest}${qs.toString() ? `?${qs}` : ''}`;
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
/** Run one tool → the text it answers with. Throws on a platform error (reported as a tool error). */
|
|
58
|
+
async function runTool(ctx, name, args = {}) {
|
|
59
|
+
if (name === 'list_docs') {
|
|
60
|
+
const { data } = await ctx.call('GET', route());
|
|
61
|
+
return [...(data.docs || [])].sort((a, b) => (a.order ?? 1e9) - (b.order ?? 1e9))
|
|
62
|
+
.map((d) => `${docName(d.key)} | ${d.section_title || d.category || ''} | ${d.title || ''} | updated ${String(d.updated_at || '').slice(0, 10)} | ${d.description || ''}`).join('\n');
|
|
63
|
+
}
|
|
64
|
+
if (name === 'read_doc') {
|
|
65
|
+
if (!args.doc) throw new Error('doc is required');
|
|
66
|
+
const { data } = await ctx.call('GET', route(`/${encodeURIComponent(docName(args.doc))}`, { section: args.section }));
|
|
67
|
+
return `${data.title || data.key} (${data.key}, updated ${String(data.updated_at || '').slice(0, 10)}${data.section ? `, section "${data.section}"` : ''})\n\n${data.content}`;
|
|
68
|
+
}
|
|
69
|
+
if (name === 'search_docs') {
|
|
70
|
+
if (!args.query) throw new Error('query is required');
|
|
71
|
+
const { data } = await ctx.call('GET', route('', { q: args.query, limit: args.limit }));
|
|
72
|
+
if (!data.results.length) return `Nothing in the docs mentions all of: ${args.query}`;
|
|
73
|
+
return data.results.map((r) => [`${docName(r.key)} (${r.title})`, ...r.sections.map((s) => ` § ${s.heading || r.title}: ${s.snippet}`)].join('\n')).join('\n');
|
|
74
|
+
}
|
|
75
|
+
if (name === 'docs_changes') {
|
|
76
|
+
const since = args.since || new Date(Date.now() - 7 * 864e5).toISOString().slice(0, 10);
|
|
77
|
+
const { data } = await ctx.call('GET', route('', { since }));
|
|
78
|
+
return data.docs.length ? data.docs.map((d) => `${String(d.updated_at).slice(0, 10)} ${docName(d.key)} | ${d.title || ''}`).join('\n') : `No doc changed since ${since}.`;
|
|
79
|
+
}
|
|
80
|
+
throw Object.assign(new Error(`unknown tool ${name}`), { rpc: -32602 });
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** One JSON-RPC message → the response object, or null for a notification. */
|
|
84
|
+
async function handle(ctx, msg) {
|
|
85
|
+
const reply = (result) => ({ jsonrpc: '2.0', id: msg.id, result });
|
|
86
|
+
const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id, error: { code, message } });
|
|
87
|
+
const isNotification = msg.id === undefined || msg.id === null;
|
|
88
|
+
switch (msg.method) {
|
|
89
|
+
case 'initialize':
|
|
90
|
+
return reply({
|
|
91
|
+
protocolVersion: (msg.params && msg.params.protocolVersion) || '2025-06-18',
|
|
92
|
+
capabilities: { tools: {} },
|
|
93
|
+
serverInfo: { name: 'plaiful', version },
|
|
94
|
+
instructions: INSTRUCTIONS,
|
|
95
|
+
});
|
|
96
|
+
case 'notifications/initialized':
|
|
97
|
+
case 'notifications/cancelled':
|
|
98
|
+
return null;
|
|
99
|
+
case 'ping':
|
|
100
|
+
return reply({});
|
|
101
|
+
case 'tools/list':
|
|
102
|
+
return reply({ tools: TOOLS });
|
|
103
|
+
case 'tools/call': {
|
|
104
|
+
const { name, arguments: args } = msg.params || {};
|
|
105
|
+
if (!TOOLS.some((t) => t.name === name)) return fail(-32602, `unknown tool ${name}`);
|
|
106
|
+
try {
|
|
107
|
+
return reply({ content: [{ type: 'text', text: await runTool(ctx, name, args || {}) }] });
|
|
108
|
+
} catch (e) {
|
|
109
|
+
return reply({ content: [{ type: 'text', text: `Plaiful: ${e.message}` }], isError: true });
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
default:
|
|
113
|
+
return isNotification ? null : fail(-32601, `method not found: ${msg.method}`);
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Serve until stdin closes. → exit code */
|
|
118
|
+
function serve(ctx) {
|
|
119
|
+
const stdin = ctx.io.stdin || process.stdin;
|
|
120
|
+
const write = (obj) => ctx.io.stdout.write(`${JSON.stringify(obj)}\n`);
|
|
121
|
+
let buf = '';
|
|
122
|
+
let pending = Promise.resolve();
|
|
123
|
+
return new Promise((resolve) => {
|
|
124
|
+
stdin.setEncoding && stdin.setEncoding('utf8');
|
|
125
|
+
stdin.on('data', (chunk) => {
|
|
126
|
+
buf += chunk;
|
|
127
|
+
let nl;
|
|
128
|
+
while ((nl = buf.indexOf('\n')) >= 0) {
|
|
129
|
+
const line = buf.slice(0, nl).trim();
|
|
130
|
+
buf = buf.slice(nl + 1);
|
|
131
|
+
if (!line) continue;
|
|
132
|
+
let msg;
|
|
133
|
+
try { msg = JSON.parse(line); } catch {
|
|
134
|
+
write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
|
|
135
|
+
continue;
|
|
136
|
+
}
|
|
137
|
+
pending = pending.then(() => handle(ctx, msg)).then((r) => { if (r) write(r); })
|
|
138
|
+
.catch((e) => { if (msg.id !== undefined) write({ jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: e.message } }); });
|
|
139
|
+
}
|
|
140
|
+
});
|
|
141
|
+
stdin.on('end', () => pending.then(() => resolve(0)));
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
module.exports = { serve, handle, TOOLS };
|