@contentgrapher-io/mcp-server 1.1.1
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 +28 -0
- package/LICENSE +21 -0
- package/README.md +193 -0
- package/dist/api-client.js +108 -0
- package/dist/config.js +18 -0
- package/dist/credit-cache.js +17 -0
- package/dist/errors.js +105 -0
- package/dist/formatters/analysis-text.js +107 -0
- package/dist/formatters/audience.js +11 -0
- package/dist/formatters/concept-map.js +31 -0
- package/dist/formatters/coverage-score.js +29 -0
- package/dist/formatters/page-architecture.js +16 -0
- package/dist/formatters/quality-signals.js +15 -0
- package/dist/formatters/question-labels.js +34 -0
- package/dist/formatters/recommendations.js +20 -0
- package/dist/index.js +17 -0
- package/dist/key-validation.js +21 -0
- package/dist/progress.js +40 -0
- package/dist/semaphore.js +42 -0
- package/dist/server.js +220 -0
- package/dist/signals.js +26 -0
- package/dist/tool-runtime.js +50 -0
- package/dist/tools/analyze-url-phase1.js +47 -0
- package/dist/tools/analyze-url.js +100 -0
- package/dist/tools/check-credits.js +19 -0
- package/dist/tools/complete-analysis.js +94 -0
- package/dist/tools/get-analysis.js +31 -0
- package/dist/types.js +31 -0
- package/package.json +55 -0
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { getCachedCredits, setCachedCredits, } from "../credit-cache.js";
|
|
2
|
+
import { buildPhase2Text } from "../formatters/analysis-text.js";
|
|
3
|
+
import { validateUrlFormat } from "../key-validation.js";
|
|
4
|
+
import { sendProgressNow, startProgressTicker, } from "../progress.js";
|
|
5
|
+
import { sharedSemaphore, withSemaphore } from "../semaphore.js";
|
|
6
|
+
import { analysisResource, errorResult, textItem, toolErrorFromException, } from "../tool-runtime.js";
|
|
7
|
+
const URL_INVALID = "The url field is missing, empty, or not a valid http(s) URL. Provide a publicly accessible URL such as https://example.com/docs/getting-started.";
|
|
8
|
+
const AUDIENCE_TOO_LONG = "The audience parameter exceeds 500 characters. Shorten it and try again.";
|
|
9
|
+
const ZERO_CREDITS = "No purchased credits remaining (balance: 0). Phase 2 analyses require purchased credits. Purchase a credit pack at https://contentgrapher.io/pricing before running analyze_url. To run only Phase 1 (free), use analyze_url_phase1.";
|
|
10
|
+
export async function runAnalyzeUrl(args, ctx) {
|
|
11
|
+
if (!args.url || !validateUrlFormat(args.url)) {
|
|
12
|
+
return errorResult(URL_INVALID);
|
|
13
|
+
}
|
|
14
|
+
if (args.audience !== undefined && args.audience.length > 500) {
|
|
15
|
+
return errorResult(AUDIENCE_TOO_LONG);
|
|
16
|
+
}
|
|
17
|
+
let credits = getCachedCredits();
|
|
18
|
+
if (credits === 0) {
|
|
19
|
+
try {
|
|
20
|
+
const me = await ctx.client.getMe("analyze_url");
|
|
21
|
+
setCachedCredits(me.creditsRemaining);
|
|
22
|
+
credits = me.creditsRemaining;
|
|
23
|
+
}
|
|
24
|
+
catch (err) {
|
|
25
|
+
return toolErrorFromException(err);
|
|
26
|
+
}
|
|
27
|
+
if (credits === 0)
|
|
28
|
+
return errorResult(ZERO_CREDITS);
|
|
29
|
+
}
|
|
30
|
+
const startedAt = Date.now();
|
|
31
|
+
let analysisId = null;
|
|
32
|
+
let phase1Complete = false;
|
|
33
|
+
try {
|
|
34
|
+
return await withSemaphore(sharedSemaphore, async () => {
|
|
35
|
+
const stopPhase1 = startProgressTicker({
|
|
36
|
+
progressToken: ctx.progressToken,
|
|
37
|
+
send: ctx.sendProgress,
|
|
38
|
+
message: (s) => `Phase 1 in progress — building concept map. Elapsed: ${s}s. Typical: 30-60s, worst case: ~290s.`,
|
|
39
|
+
doneMessage: "Phase 1 complete.",
|
|
40
|
+
});
|
|
41
|
+
let phase1;
|
|
42
|
+
try {
|
|
43
|
+
phase1 = await ctx.client.createPhase1({
|
|
44
|
+
url: args.url,
|
|
45
|
+
audience: args.audience,
|
|
46
|
+
}, "analyze_url");
|
|
47
|
+
}
|
|
48
|
+
finally {
|
|
49
|
+
stopPhase1();
|
|
50
|
+
}
|
|
51
|
+
analysisId = phase1.analysisId;
|
|
52
|
+
phase1Complete = true;
|
|
53
|
+
const elapsed = Math.round((Date.now() - startedAt) / 1000);
|
|
54
|
+
await sendProgressNow(ctx.sendProgress, ctx.progressToken, `Phase 1 complete. Analysis ID: ${phase1.analysisId}. Starting Phase 2 analysis (costs 1 credit). Elapsed so far: ${elapsed}s.`, 1);
|
|
55
|
+
const stopPhase2 = startProgressTicker({
|
|
56
|
+
progressToken: ctx.progressToken,
|
|
57
|
+
send: ctx.sendProgress,
|
|
58
|
+
message: (s) => `Phase 2 in progress — scoring coverage and generating recommendations. Analysis ID: ${phase1.analysisId}. Elapsed: ${s}s. Typical: 40-88s, worst case: ~275s.`,
|
|
59
|
+
doneMessage: "done",
|
|
60
|
+
});
|
|
61
|
+
let phase2;
|
|
62
|
+
try {
|
|
63
|
+
phase2 = await ctx.client.completePhase2(phase1.analysisId, {
|
|
64
|
+
audience: args.audience,
|
|
65
|
+
}, "analyze_url");
|
|
66
|
+
}
|
|
67
|
+
finally {
|
|
68
|
+
stopPhase2();
|
|
69
|
+
}
|
|
70
|
+
let creditsAfter = null;
|
|
71
|
+
try {
|
|
72
|
+
const me = await ctx.client.getMe("analyze_url");
|
|
73
|
+
setCachedCredits(me.creditsRemaining);
|
|
74
|
+
creditsAfter = me.creditsRemaining;
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
creditsAfter = null;
|
|
78
|
+
}
|
|
79
|
+
const text = buildPhase2Text({
|
|
80
|
+
url: args.url,
|
|
81
|
+
audience: args.audience,
|
|
82
|
+
resource: phase2,
|
|
83
|
+
creditsRemaining: creditsAfter,
|
|
84
|
+
});
|
|
85
|
+
return {
|
|
86
|
+
content: [textItem(text), analysisResource(phase2.analysisId, phase2)],
|
|
87
|
+
};
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
catch (err) {
|
|
91
|
+
return toolErrorFromException(err, {
|
|
92
|
+
analysisId,
|
|
93
|
+
phase1Complete,
|
|
94
|
+
timeoutCtx: analysisId
|
|
95
|
+
? { phase: "phase2", analysisId }
|
|
96
|
+
: { phase: "phase1" },
|
|
97
|
+
networkCtx: analysisId ? { analysisId } : undefined,
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { setCachedCredits } from "../credit-cache.js";
|
|
2
|
+
import { textItem, toolErrorFromException, } from "../tool-runtime.js";
|
|
3
|
+
const TAIL = `\n\nNote: Only purchased credits can be used via the API. Gift or admin credits (if any) are visible in the web app but cannot be debited programmatically. If the web app shows a non-zero balance but Phase 2 calls return a 402 error, your balance consists entirely of gift or admin credits.`;
|
|
4
|
+
export async function runCheckCredits(ctx) {
|
|
5
|
+
try {
|
|
6
|
+
const me = await ctx.client.getMe("check_credits");
|
|
7
|
+
setCachedCredits(me.creditsRemaining);
|
|
8
|
+
const text = `ContentGrapher account status:\n` +
|
|
9
|
+
`- Purchased credits remaining: ${me.creditsRemaining}\n` +
|
|
10
|
+
`- Total credits purchased: ${me.creditsPurchased}\n` +
|
|
11
|
+
`- Active API keys: ${me.keysCount}\n` +
|
|
12
|
+
`- Total analyses run: ${me.totalAnalyses}` +
|
|
13
|
+
TAIL;
|
|
14
|
+
return { content: [textItem(text)] };
|
|
15
|
+
}
|
|
16
|
+
catch (err) {
|
|
17
|
+
return toolErrorFromException(err);
|
|
18
|
+
}
|
|
19
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { getCachedCredits, setCachedCredits, } from "../credit-cache.js";
|
|
2
|
+
import { ApiError } from "../errors.js";
|
|
3
|
+
import { buildPhase2Text } from "../formatters/analysis-text.js";
|
|
4
|
+
import { validateAnalysisId } from "../key-validation.js";
|
|
5
|
+
import { startProgressTicker } from "../progress.js";
|
|
6
|
+
import { sharedSemaphore, withSemaphore } from "../semaphore.js";
|
|
7
|
+
import { analysisResource, errorResult, textItem, toolErrorFromException, } from "../tool-runtime.js";
|
|
8
|
+
const ID_INVALID = "The analysisId is missing or not a valid UUID. Pass the id returned by a previous call to analyze_url_phase1, analyze_url, or complete_analysis.";
|
|
9
|
+
const AUDIENCE_TOO_LONG = "The audience parameter exceeds 500 characters. Shorten it and try again.";
|
|
10
|
+
const ZERO_CREDITS = "No purchased credits remaining (balance: 0). Phase 2 analyses require purchased credits. Gift or admin credits visible in the web app cannot be debited via the API. Purchase a credit pack at https://contentgrapher.io/pricing.";
|
|
11
|
+
export async function runCompleteAnalysis(args, ctx) {
|
|
12
|
+
if (!args.analysisId || !validateAnalysisId(args.analysisId)) {
|
|
13
|
+
return errorResult(ID_INVALID);
|
|
14
|
+
}
|
|
15
|
+
if (args.audience !== undefined && args.audience.length > 500) {
|
|
16
|
+
return errorResult(AUDIENCE_TOO_LONG);
|
|
17
|
+
}
|
|
18
|
+
let existing;
|
|
19
|
+
try {
|
|
20
|
+
existing = await ctx.client.getAnalysis(args.analysisId, "complete_analysis");
|
|
21
|
+
}
|
|
22
|
+
catch (err) {
|
|
23
|
+
if (err instanceof ApiError && err.status === 404) {
|
|
24
|
+
return toolErrorFromException(err, { analysisId: args.analysisId });
|
|
25
|
+
}
|
|
26
|
+
return toolErrorFromException(err, { analysisId: args.analysisId });
|
|
27
|
+
}
|
|
28
|
+
if (existing.status === "complete") {
|
|
29
|
+
const phase2 = existing;
|
|
30
|
+
const text = buildPhase2Text({
|
|
31
|
+
audience: args.audience,
|
|
32
|
+
resource: phase2,
|
|
33
|
+
creditsRemaining: getCachedCredits(),
|
|
34
|
+
});
|
|
35
|
+
return {
|
|
36
|
+
content: [textItem(text), analysisResource(phase2.analysisId, phase2)],
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
let credits = getCachedCredits();
|
|
40
|
+
if (credits === 0) {
|
|
41
|
+
try {
|
|
42
|
+
const me = await ctx.client.getMe("complete_analysis");
|
|
43
|
+
setCachedCredits(me.creditsRemaining);
|
|
44
|
+
credits = me.creditsRemaining;
|
|
45
|
+
}
|
|
46
|
+
catch (err) {
|
|
47
|
+
return toolErrorFromException(err, { analysisId: args.analysisId });
|
|
48
|
+
}
|
|
49
|
+
if (credits === 0)
|
|
50
|
+
return errorResult(ZERO_CREDITS);
|
|
51
|
+
}
|
|
52
|
+
try {
|
|
53
|
+
return await withSemaphore(sharedSemaphore, async () => {
|
|
54
|
+
const stop = startProgressTicker({
|
|
55
|
+
progressToken: ctx.progressToken,
|
|
56
|
+
send: ctx.sendProgress,
|
|
57
|
+
message: (s) => `Phase 2 in progress — scoring coverage and generating recommendations. Analysis ID: ${args.analysisId}. Elapsed: ${s}s. Typical: 40-88s, worst case: ~275s.`,
|
|
58
|
+
doneMessage: "done",
|
|
59
|
+
});
|
|
60
|
+
try {
|
|
61
|
+
const phase2 = await ctx.client.completePhase2(args.analysisId, {
|
|
62
|
+
audience: args.audience,
|
|
63
|
+
}, "complete_analysis");
|
|
64
|
+
let creditsAfter = null;
|
|
65
|
+
try {
|
|
66
|
+
const me = await ctx.client.getMe("complete_analysis");
|
|
67
|
+
setCachedCredits(me.creditsRemaining);
|
|
68
|
+
creditsAfter = me.creditsRemaining;
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
creditsAfter = null;
|
|
72
|
+
}
|
|
73
|
+
const text = buildPhase2Text({
|
|
74
|
+
audience: args.audience,
|
|
75
|
+
resource: phase2,
|
|
76
|
+
creditsRemaining: creditsAfter,
|
|
77
|
+
});
|
|
78
|
+
return {
|
|
79
|
+
content: [textItem(text), analysisResource(phase2.analysisId, phase2)],
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
finally {
|
|
83
|
+
stop();
|
|
84
|
+
}
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
catch (err) {
|
|
88
|
+
return toolErrorFromException(err, {
|
|
89
|
+
analysisId: args.analysisId,
|
|
90
|
+
timeoutCtx: { phase: "phase2", analysisId: args.analysisId },
|
|
91
|
+
networkCtx: { analysisId: args.analysisId },
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { buildPhase1OnlyFromGetText, buildPhase2Text, } from "../formatters/analysis-text.js";
|
|
2
|
+
import { getCachedCredits } from "../credit-cache.js";
|
|
3
|
+
import { validateAnalysisId } from "../key-validation.js";
|
|
4
|
+
import { analysisResource, errorResult, textItem, toolErrorFromException, } from "../tool-runtime.js";
|
|
5
|
+
const ID_INVALID = "The analysisId is missing or not a valid UUID. Pass the id returned by a previous call to analyze_url_phase1, analyze_url, or complete_analysis.";
|
|
6
|
+
const UNEXPECTED_STATUS = "ContentGrapher returned an unexpected analysis status. Wait 30 seconds and retry. If the problem persists, contact support.";
|
|
7
|
+
export async function runGetAnalysis(args, ctx) {
|
|
8
|
+
if (!args.analysisId || !validateAnalysisId(args.analysisId)) {
|
|
9
|
+
return errorResult(ID_INVALID);
|
|
10
|
+
}
|
|
11
|
+
try {
|
|
12
|
+
const r = await ctx.client.getAnalysis(args.analysisId, "get_analysis");
|
|
13
|
+
if (r.status === "complete") {
|
|
14
|
+
const phase2 = r;
|
|
15
|
+
const text = buildPhase2Text({
|
|
16
|
+
resource: phase2,
|
|
17
|
+
creditsRemaining: getCachedCredits(),
|
|
18
|
+
});
|
|
19
|
+
return { content: [textItem(text), analysisResource(phase2.analysisId, phase2)] };
|
|
20
|
+
}
|
|
21
|
+
if (r.status === "phase1_complete") {
|
|
22
|
+
const phase1 = r;
|
|
23
|
+
const text = buildPhase1OnlyFromGetText(phase1);
|
|
24
|
+
return { content: [textItem(text), analysisResource(phase1.analysisId, phase1)] };
|
|
25
|
+
}
|
|
26
|
+
return errorResult(UNEXPECTED_STATUS);
|
|
27
|
+
}
|
|
28
|
+
catch (err) {
|
|
29
|
+
return toolErrorFromException(err, { analysisId: args.analysisId });
|
|
30
|
+
}
|
|
31
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
const COMPLETE_BAND_MIN = 0.70;
|
|
2
|
+
/**
|
|
3
|
+
* Port of contentgrapher.io/lib/coverage.ts isAnalysisDone — the single source
|
|
4
|
+
* of truth for "is this page done?". Computed from already-returned Phase 2
|
|
5
|
+
* fields; never feeds the score pipeline.
|
|
6
|
+
*/
|
|
7
|
+
export function computeDone(r) {
|
|
8
|
+
if (r.pageArchitecture?.structuralDecision === "split") {
|
|
9
|
+
return { done: false, reason: "split" };
|
|
10
|
+
}
|
|
11
|
+
const framework = r.explanationFramework;
|
|
12
|
+
const concepts = Array.isArray(framework?.concepts) ? framework.concepts : [];
|
|
13
|
+
const essentials = concepts.filter((c) => typeof c === "object" &&
|
|
14
|
+
c !== null &&
|
|
15
|
+
c["priority"] === "essential" &&
|
|
16
|
+
typeof c["alreadyPresent"] === "string");
|
|
17
|
+
if (essentials.some((c) => c.alreadyPresent === "no")) {
|
|
18
|
+
return { done: false, reason: "missing_essentials" };
|
|
19
|
+
}
|
|
20
|
+
if (essentials.some((c) => c.alreadyPresent === "partial")) {
|
|
21
|
+
return { done: false, reason: "partial_essentials" };
|
|
22
|
+
}
|
|
23
|
+
const score = r.coverageScore;
|
|
24
|
+
if (score === null || !Number.isFinite(score)) {
|
|
25
|
+
return { done: false, reason: "no_score" };
|
|
26
|
+
}
|
|
27
|
+
if (score < COMPLETE_BAND_MIN) {
|
|
28
|
+
return { done: false, reason: "below_complete_band" };
|
|
29
|
+
}
|
|
30
|
+
return { done: true, reason: "done" };
|
|
31
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@contentgrapher-io/mcp-server",
|
|
3
|
+
"version": "1.1.1",
|
|
4
|
+
"description": "MCP server for ContentGrapher: structural completeness analysis for web content. Wraps ContentGrapher REST API v1.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=20.0.0"
|
|
9
|
+
},
|
|
10
|
+
"main": "dist/index.js",
|
|
11
|
+
"bin": {
|
|
12
|
+
"contentgrapher-mcp": "dist/index.js"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"README.md",
|
|
17
|
+
"CHANGELOG.md",
|
|
18
|
+
"LICENSE"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"build": "tsc",
|
|
22
|
+
"prepare": "npm run build",
|
|
23
|
+
"prepublishOnly": "npm run build && npm test",
|
|
24
|
+
"test": "tsx --test tests/*.test.ts",
|
|
25
|
+
"start": "node dist/index.js"
|
|
26
|
+
},
|
|
27
|
+
"dependencies": {
|
|
28
|
+
"@modelcontextprotocol/sdk": "^1.29.0"
|
|
29
|
+
},
|
|
30
|
+
"devDependencies": {
|
|
31
|
+
"@types/node": "^20.11.0",
|
|
32
|
+
"tsx": "^4.7.0",
|
|
33
|
+
"typescript": "^5.4.0"
|
|
34
|
+
},
|
|
35
|
+
"keywords": [
|
|
36
|
+
"mcp",
|
|
37
|
+
"model-context-protocol",
|
|
38
|
+
"contentgrapher",
|
|
39
|
+
"content-analysis",
|
|
40
|
+
"documentation",
|
|
41
|
+
"technical-writing",
|
|
42
|
+
"llm-retrieval",
|
|
43
|
+
"structural-completeness",
|
|
44
|
+
"devrel",
|
|
45
|
+
"docs-as-code"
|
|
46
|
+
],
|
|
47
|
+
"repository": {
|
|
48
|
+
"type": "git",
|
|
49
|
+
"url": "git+https://github.com/contentgrapher/mcp-server.git"
|
|
50
|
+
},
|
|
51
|
+
"bugs": {
|
|
52
|
+
"url": "https://github.com/contentgrapher/mcp-server/issues"
|
|
53
|
+
},
|
|
54
|
+
"homepage": "https://contentgrapher.io/docs/mcp"
|
|
55
|
+
}
|