@contentgrapher-io/mcp-server 1.1.1 → 1.1.2
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 +14 -1
- package/README.md +12 -10
- package/dist/api-client.js +2 -0
- package/dist/errors.js +12 -4
- package/dist/formatters/accepted-plan.js +41 -0
- package/dist/formatters/analysis-text.js +11 -24
- package/dist/progress.js +1 -6
- package/dist/server.js +4 -1
- package/dist/tools/analyze-url-phase1.js +8 -3
- package/dist/tools/analyze-url.js +2 -2
- package/dist/tools/complete-analysis.js +16 -2
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,11 +1,24 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
All notable changes to `@contentgrapher/mcp-server`.
|
|
3
|
+
All notable changes to `@contentgrapher-io/mcp-server`.
|
|
4
4
|
|
|
5
5
|
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This package follows [semantic versioning](https://semver.org/spec/v2.0.0.html) and tracks the ContentGrapher REST API major version.
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [1.1.2]
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
|
|
13
|
+
- Keep recovery guidance accurate when execution or credit settlement is unknown; identify an active execution without suggesting a new analysis.
|
|
14
|
+
- Correct package repository links and repair the publishing workflow.
|
|
15
|
+
- Preserve report order and all accepted editing steps in embedded report data. Label subject importance without presenting it as editing urgency.
|
|
16
|
+
- Respect unavailable reports and audience/source mismatches without repeating a credit-bearing completion.
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
|
|
20
|
+
- Support the optional report contract and exact analyzed-source handoff, while retaining compatibility with source-omitting servers.
|
|
21
|
+
|
|
9
22
|
## [1.0.1]
|
|
10
23
|
|
|
11
24
|
### Fixed
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# @contentgrapher/mcp-server
|
|
1
|
+
# @contentgrapher-io/mcp-server
|
|
2
2
|
|
|
3
3
|
Model Context Protocol server for [ContentGrapher](https://contentgrapher.io). Analyze web pages for structural concept completeness from Claude Code, Cursor, Windsurf, or VS Code Copilot.
|
|
4
4
|
|
|
@@ -20,6 +20,8 @@ ContentGrapher returns an observed concept map, 8-dimension question coverage, a
|
|
|
20
20
|
| `analyze_url` | 1 credit | Phase 1 + Phase 2 in one call |
|
|
21
21
|
| `get_analysis` | Free | Retrieve a prior analysis result by ID |
|
|
22
22
|
|
|
23
|
+
This client declares support for `accepted-plan-v1`. For reports using that contract, text and the embedded resource preserve accepted actions, page scope, examples, review items, and unknown completion. A saved report is shown with its recorded audience; changing the audience requires a new analysis. Unsupported or invalid optional plans are reported as unavailable rather than replaced with raw suggestions.
|
|
24
|
+
|
|
23
25
|
Each tool that returns an analysis also returns an embedded `application/json` resource at `contentgrapher://analyses/{id}` containing the full response body.
|
|
24
26
|
|
|
25
27
|
## Configuration
|
|
@@ -35,7 +37,7 @@ Generate a key at [contentgrapher.io/account](https://contentgrapher.io/account)
|
|
|
35
37
|
"mcpServers": {
|
|
36
38
|
"contentgrapher": {
|
|
37
39
|
"command": "npx",
|
|
38
|
-
"args": ["-y", "@contentgrapher/mcp-server@1"],
|
|
40
|
+
"args": ["-y", "@contentgrapher-io/mcp-server@1"],
|
|
39
41
|
"env": {
|
|
40
42
|
"CONTENTGRAPHER_API_KEY": "cgk_your_key_here"
|
|
41
43
|
},
|
|
@@ -56,7 +58,7 @@ The `timeout: 600000` value (10 minutes in milliseconds) accommodates worst-case
|
|
|
56
58
|
"mcpServers": {
|
|
57
59
|
"contentgrapher": {
|
|
58
60
|
"command": "npx",
|
|
59
|
-
"args": ["-y", "@contentgrapher/mcp-server@1"],
|
|
61
|
+
"args": ["-y", "@contentgrapher-io/mcp-server@1"],
|
|
60
62
|
"env": {
|
|
61
63
|
"CONTENTGRAPHER_API_KEY": "cgk_your_key_here"
|
|
62
64
|
}
|
|
@@ -76,7 +78,7 @@ The `timeout: 600000` value (10 minutes in milliseconds) accommodates worst-case
|
|
|
76
78
|
"mcpServers": {
|
|
77
79
|
"contentgrapher": {
|
|
78
80
|
"command": "npx",
|
|
79
|
-
"args": ["-y", "@contentgrapher/mcp-server@1"],
|
|
81
|
+
"args": ["-y", "@contentgrapher-io/mcp-server@1"],
|
|
80
82
|
"env": {
|
|
81
83
|
"CONTENTGRAPHER_API_KEY": "${env:CONTENTGRAPHER_API_KEY}"
|
|
82
84
|
}
|
|
@@ -95,7 +97,7 @@ The `timeout: 600000` value (10 minutes in milliseconds) accommodates worst-case
|
|
|
95
97
|
"contentgrapher": {
|
|
96
98
|
"type": "stdio",
|
|
97
99
|
"command": "npx",
|
|
98
|
-
"args": ["-y", "@contentgrapher/mcp-server@1"],
|
|
100
|
+
"args": ["-y", "@contentgrapher-io/mcp-server@1"],
|
|
99
101
|
"env": {
|
|
100
102
|
"CONTENTGRAPHER_API_KEY": "cgk_your_key_here"
|
|
101
103
|
}
|
|
@@ -125,7 +127,7 @@ To retrieve a prior result:
|
|
|
125
127
|
## API key handling
|
|
126
128
|
|
|
127
129
|
- The server reads `CONTENTGRAPHER_API_KEY` at startup, validates the format, and deletes it from `process.env`.
|
|
128
|
-
- The key is sent only to `https://contentgrapher.io` over HTTPS. It is never logged.
|
|
130
|
+
- The key is sent only to `https://www.contentgrapher.io` over HTTPS. It is never logged.
|
|
129
131
|
- The server is stateless. Analysis results are returned to your MCP host and not persisted by the server beyond a 60-second purchased-credits cache.
|
|
130
132
|
|
|
131
133
|
### Pinning the version
|
|
@@ -133,7 +135,7 @@ To retrieve a prior result:
|
|
|
133
135
|
The configuration examples above use `@1` to accept all v1.x updates. To pin to an exact version:
|
|
134
136
|
|
|
135
137
|
```json
|
|
136
|
-
"args": ["-y", "@contentgrapher/mcp-server@1.
|
|
138
|
+
"args": ["-y", "@contentgrapher-io/mcp-server@1.1.2"]
|
|
137
139
|
```
|
|
138
140
|
|
|
139
141
|
## Concurrency
|
|
@@ -155,7 +157,7 @@ If a tool call is interrupted by a network failure or host timeout:
|
|
|
155
157
|
1. Note the `analysisId` from the most recent progress notification or tool response.
|
|
156
158
|
2. Call `get_analysis` with that ID:
|
|
157
159
|
- `status: "complete"` means Phase 2 finished and your credit was used. The full result is in the response.
|
|
158
|
-
- `status: "phase1_complete"` means
|
|
160
|
+
- `status: "phase1_complete"` means a Phase 1 result is available, but does not establish whether Phase 2 is still running, failed, or awaiting settlement. Wait and check the same ID again. Open the report in the web app for recovery status before deciding to retry.
|
|
159
161
|
3. Do not call `analyze_url` again on the same URL without checking the prior `analysisId` first.
|
|
160
162
|
|
|
161
163
|
Calling `complete_analysis` on an analysis that is already `status: "complete"` returns the stored result without debiting a second credit.
|
|
@@ -189,5 +191,5 @@ MIT — see [LICENSE](LICENSE).
|
|
|
189
191
|
- ContentGrapher: [contentgrapher.io](https://contentgrapher.io)
|
|
190
192
|
- Account and key management: [contentgrapher.io/account](https://contentgrapher.io/account)
|
|
191
193
|
- Pricing: [contentgrapher.io/pricing](https://contentgrapher.io/pricing)
|
|
192
|
-
-
|
|
193
|
-
- Issues: [github.com/contentgrapher/mcp-server/issues](https://github.com/
|
|
194
|
+
- Product reference: [contentgrapher.io/help](https://www.contentgrapher.io/help)
|
|
195
|
+
- Issues: [github.com/contentgrapher/mcp-server/issues](https://github.com/danielkcheung/mcp-server/issues)
|
package/dist/api-client.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { ACCEPTED_PLAN_VERSION } from './formatters/accepted-plan.js';
|
|
1
2
|
import { readFileSync } from "node:fs";
|
|
2
3
|
import { dirname, join } from "node:path";
|
|
3
4
|
import { fileURLToPath } from "node:url";
|
|
@@ -39,6 +40,7 @@ export class ApiClient {
|
|
|
39
40
|
headers: {
|
|
40
41
|
Authorization: `Bearer ${this.opts.apiKey}`,
|
|
41
42
|
Accept: "application/json",
|
|
43
|
+
"X-ContentGrapher-Report-Contract": ACCEPTED_PLAN_VERSION,
|
|
42
44
|
...(opts.body !== undefined
|
|
43
45
|
? { "Content-Type": "application/json" }
|
|
44
46
|
: {}),
|
package/dist/errors.js
CHANGED
|
@@ -63,23 +63,31 @@ export function describe503(analysisId) {
|
|
|
63
63
|
const tail = analysisId
|
|
64
64
|
? `\n\nAnalysis ID: ${analysisId}. Call get_analysis("${analysisId}") to confirm whether a result was saved despite the error.`
|
|
65
65
|
: "";
|
|
66
|
-
return `ContentGrapher
|
|
66
|
+
return `ContentGrapher could not confirm completion. This error does not establish whether a report was saved or a credit was refunded. Check the saved report and check_credits before deciding to retry. A retry must use the same analysis ID; do not start a new analyze_url call to recover an interrupted analysis.${tail}`;
|
|
67
67
|
}
|
|
68
68
|
export const DESCRIBE_SEMAPHORE_SATURATED = "Too many concurrent analyses in progress on this API key (maximum 4 via MCP server). Wait for a current analysis to complete before starting another.";
|
|
69
69
|
export function describePhase1Timeout() {
|
|
70
70
|
return "Phase 1 did not complete within 295 seconds. The analysis may still be running on the ContentGrapher server. There is no analysisId to recover with: Phase 1 did not persist a result before timing out. If this URL consistently times out, the page may be too large for reliable analysis. Try again or try a shorter page.";
|
|
71
71
|
}
|
|
72
72
|
export function describePhase2Timeout(analysisId) {
|
|
73
|
-
return `Phase 2 did not
|
|
73
|
+
return `Phase 2 did not respond within 280 seconds. Analysis ID: ${analysisId}. The analysis may still be running. Call get_analysis("${analysisId}") to check for a saved result. A "phase1_complete" response does not establish Phase 2 execution or credit settlement status. Wait and check the same ID again, or open the report in the web app for recovery status. Do not call analyze_url again to recover this analysis.`;
|
|
74
74
|
}
|
|
75
75
|
export function describePhase2NetworkError(analysisId) {
|
|
76
|
-
return `The connection to ContentGrapher was interrupted during Phase 2. Analysis ID: ${analysisId}. Call get_analysis("${analysisId}") to
|
|
76
|
+
return `The connection to ContentGrapher was interrupted during Phase 2. Analysis ID: ${analysisId}. Call get_analysis("${analysisId}") to check for a saved result. A "phase1_complete" response does not establish whether Phase 2 is running, failed, or awaiting credit settlement. Wait and check the same ID again, or open the report in the web app for recovery status. Do not call analyze_url again to recover this analysis.`;
|
|
77
77
|
}
|
|
78
78
|
export function describe402AfterPhase1(analysisId) {
|
|
79
79
|
return `Phase 1 completed successfully. Analysis ID: ${analysisId}. Phase 2 could not start: no purchased credits remaining. Your Phase 1 result is saved. Purchase credits at https://contentgrapher.io/pricing and call complete_analysis("${analysisId}") to run Phase 2 without repeating Phase 1. Your Phase 1 result is stored and will not expire.`;
|
|
80
80
|
}
|
|
81
81
|
export function describeApiError(err, ctx = {}) {
|
|
82
82
|
const aid = ctx.analysisId ?? null;
|
|
83
|
+
if (err.body?.error === "report_contract_unsupported")
|
|
84
|
+
return "This report requires an updated ContentGrapher client. Update the MCP server or open the report in the web app. No new analysis was charged.";
|
|
85
|
+
if (["effective_input_mismatch", "input_provenance_unknown"].includes(err.body?.error ?? ""))
|
|
86
|
+
return "The saved report has different or unknown effective inputs. Read it without overrides, or start a new analysis. No new analysis was charged.";
|
|
87
|
+
if (err.body?.error === "execution_active")
|
|
88
|
+
return `An execution is already active for this analysis. No additional execution was started by this request. ${aid ? `Call get_analysis("${aid}") to check for a saved result. ` : ""}Wait and check again, or open the report in the web app for recovery status. Do not start a new analysis to recover this one.`;
|
|
89
|
+
if (err.body?.error === "source_mismatch")
|
|
90
|
+
return "sourceText does not match the exact source saved for this analysis. Use the original extraction or omit sourceText. No new analysis was charged.";
|
|
83
91
|
switch (err.status) {
|
|
84
92
|
case 400:
|
|
85
93
|
return describe400(err.body);
|
|
@@ -92,7 +100,7 @@ export function describeApiError(err, ctx = {}) {
|
|
|
92
100
|
case 404:
|
|
93
101
|
return aid ? describe404(aid) : describe404("unknown");
|
|
94
102
|
case 409:
|
|
95
|
-
return DESCRIBE_409;
|
|
103
|
+
return err.body?.error === "phase1_incomplete" ? DESCRIBE_409 : "The analysis cannot proceed in its current state. Read the saved report or open it in the web app for recovery status before retrying.";
|
|
96
104
|
case 422:
|
|
97
105
|
return DESCRIBE_422;
|
|
98
106
|
case 429:
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** Versioned server contract. Reject malformed optional plans instead of reading raw suggestions. */
|
|
2
|
+
export const ACCEPTED_PLAN_VERSION = 'accepted-plan-v1';
|
|
3
|
+
const obj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
|
|
4
|
+
const strings = (v) => Array.isArray(v) && v.every(x => typeof x === 'string' && x.length > 0);
|
|
5
|
+
const importance = ['essential', 'important', 'useful'];
|
|
6
|
+
const operations = ['add', 'deepen', 'make_explicit', 'revise_sentence', 'tighten', 'integrate_briefly', 'move', 'create'];
|
|
7
|
+
export function effectiveAudience(resource) {
|
|
8
|
+
const input = resource.effectiveInputs;
|
|
9
|
+
return obj(input) && input.version === 1 && obj(input.audience) && ['explicit', 'inferred'].includes(String(input.audience.source)) && typeof input.audience.value === 'string' ? input.audience.value : null;
|
|
10
|
+
}
|
|
11
|
+
export function formatAcceptedPlan(value) {
|
|
12
|
+
if (value == null)
|
|
13
|
+
return null;
|
|
14
|
+
const unavailable = ['Editing recommendations unavailable. Open the report in a compatible client; completeness is unknown.'];
|
|
15
|
+
if (!obj(value) || value.contractVersion !== ACCEPTED_PLAN_VERSION || !obj(value.completion) || !obj(value.availability) || !Array.isArray(value.steps) || !Array.isArray(value.reviewItems))
|
|
16
|
+
return unavailable;
|
|
17
|
+
for (const key of ['evidence', 'guidance', 'architecture'])
|
|
18
|
+
if (!['available', 'unknown', 'withheld'].includes(String(value.availability[key])))
|
|
19
|
+
return unavailable;
|
|
20
|
+
if (value.availability.guidance === 'withheld')
|
|
21
|
+
return unavailable;
|
|
22
|
+
if (!['complete', 'incomplete', 'unknown'].includes(String(value.completion.coreCoverage)) || !['present', 'none', 'unknown'].includes(String(value.completion.depthWork)) || !['present', 'none', 'unknown'].includes(String(value.completion.scopeWork)))
|
|
23
|
+
return unavailable;
|
|
24
|
+
if (value.availability.evidence !== 'available' && value.completion.coreCoverage !== 'unknown')
|
|
25
|
+
return unavailable;
|
|
26
|
+
const steps = value.steps;
|
|
27
|
+
const completion = value.completion;
|
|
28
|
+
if (steps.some(s => !obj(s) || typeof s.id !== 'string' || !strings(s.subjectIds) || !s.subjectIds.length || !strings(s.subjectLabels) || s.subjectLabels.length !== s.subjectIds.length || typeof s.instruction !== 'string' || !s.instruction.trim() || !importance.includes(String(s.importance)) || !operations.includes(String(s.operation)) || !['this_page', 'separate_page'].includes(String(s.scope)) || (s.example != null && typeof s.example !== 'string') || (s.scope === 'separate_page' && (typeof s.destination !== 'string' || !s.destination.trim() || !['move', 'create'].includes(String(s.operation))))))
|
|
29
|
+
return unavailable;
|
|
30
|
+
if (new Set(steps.map(s => s.id)).size !== steps.length || steps.some(s => (s.scope === 'this_page' && ['move', 'create'].includes(String(s.operation))) || (s.scope === 'this_page' && completion.depthWork === 'none') || (s.scope === 'separate_page' && completion.scopeWork === 'none')))
|
|
31
|
+
return unavailable;
|
|
32
|
+
if (value.reviewItems.some(r => !obj(r) || typeof r.reason !== 'string' || !strings(r.subjectLabels)))
|
|
33
|
+
return unavailable;
|
|
34
|
+
return [
|
|
35
|
+
`Core coverage: ${value.completion.coreCoverage}; depth work: ${value.completion.depthWork}; scope work: ${value.completion.scopeWork}.`,
|
|
36
|
+
`${steps.length} actionable steps; ${value.reviewItems.length} items to review.`,
|
|
37
|
+
...steps.slice(0, 5).map((s, i) => `${i + 1}. [${String(s.operation).replaceAll('_', ' ').toUpperCase()}] ${s.subjectLabels.join(', ')} (${s.scope === 'this_page' ? 'this page' : `separate page: ${s.destination}`}; subject importance: ${s.importance}) — ${s.instruction}${s.example ? `\n Example: ${s.example}` : ''}`),
|
|
38
|
+
...(steps.length > 5 ? [`${steps.length - 5} additional steps are in the embedded JSON resource. No steps have been discarded.`] : []),
|
|
39
|
+
...(value.reviewItems.length ? ['Needs review (not editing instructions):', ...value.reviewItems.map(r => `- ${r.subjectLabels.join(', ')}: ${r.reason}`)] : []),
|
|
40
|
+
];
|
|
41
|
+
}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { formatAcceptedPlan, effectiveAudience } from './accepted-plan.js';
|
|
1
2
|
import { formatScoreLines } from "./coverage-score.js";
|
|
2
3
|
import { conceptMapHeading, summarizeConceptMap } from "./concept-map.js";
|
|
3
4
|
import { formatAudience, formatPhase1AudienceField } from "./audience.js";
|
|
@@ -6,7 +7,6 @@ import { formatQualitySignals } from "./quality-signals.js";
|
|
|
6
7
|
import { formatRecommendations } from "./recommendations.js";
|
|
7
8
|
import { formatBoundaryWarning, selectPrr } from "./page-architecture.js";
|
|
8
9
|
import { reportUrlFor } from "../config.js";
|
|
9
|
-
import { computeDone } from "../types.js";
|
|
10
10
|
const FULL_REPORT_HINT = "Open the full visual breakdown — concept graph, evidence panels, explanation framework — in the ContentGrapher web app";
|
|
11
11
|
const URL_NOT_AVAILABLE = "not available — retrieved by analysis ID only";
|
|
12
12
|
function blank(parts) {
|
|
@@ -41,42 +41,29 @@ export function buildPhase1Text(opts) {
|
|
|
41
41
|
`To get writing recommendations and a coverage score, call complete_analysis with analysisId: ${r.analysisId} (costs 1 credit).`,
|
|
42
42
|
]);
|
|
43
43
|
}
|
|
44
|
-
const DONE_REASON_LABEL = {
|
|
45
|
-
done: "all essential concepts covered, score in the complete band (≥ 70%)",
|
|
46
|
-
split: "page is flagged to split — two jobs, not one finished page",
|
|
47
|
-
missing_essentials: "one or more essential concepts are absent from the content",
|
|
48
|
-
partial_essentials: "one or more essential concepts are present but underdeveloped",
|
|
49
|
-
below_complete_band: "coverage score is below the complete band (< 70%)",
|
|
50
|
-
no_score: "coverage score unavailable",
|
|
51
|
-
};
|
|
52
44
|
export function buildPhase2Text(opts) {
|
|
53
45
|
const r = opts.resource;
|
|
54
46
|
const scoreLines = formatScoreLines(r.coverageScore);
|
|
55
47
|
const prr = selectPrr(r.context?.primaryRetrievalRole, r.pageArchitecture);
|
|
56
|
-
const
|
|
48
|
+
const planLines = formatAcceptedPlan(r.acceptedPlan);
|
|
49
|
+
const warning = planLines ? null : formatBoundaryWarning(r.pageArchitecture);
|
|
57
50
|
const recs = formatRecommendations(r.recommendations ?? [], r.analysisId);
|
|
58
|
-
const { done, reason } = computeDone(r);
|
|
59
|
-
const doneLabel = done
|
|
60
|
-
? `DONE — ${DONE_REASON_LABEL["done"]}`
|
|
61
|
-
: `NOT DONE — ${DONE_REASON_LABEL[reason] ?? reason}`;
|
|
62
51
|
return blank([
|
|
63
52
|
`Analysis ID: ${r.analysisId}`,
|
|
64
|
-
`Status: complete`,
|
|
65
|
-
`Done: ${doneLabel}`,
|
|
66
53
|
`URL: ${opts.url ?? URL_NOT_AVAILABLE}`,
|
|
67
54
|
`Full report: ${reportUrlFor(r.analysisId)} — ${FULL_REPORT_HINT}.`,
|
|
68
|
-
formatAudience(
|
|
55
|
+
effectiveAudience(r) ? formatAudience(effectiveAudience(r)) : 'Audience: unknown for this report',
|
|
69
56
|
"",
|
|
70
|
-
...scoreLines,
|
|
57
|
+
...(planLines ? scoreLines.slice(0, 1) : scoreLines),
|
|
71
58
|
"",
|
|
72
59
|
`Primary Retrieval Role: ${prr}`,
|
|
73
60
|
warning,
|
|
74
61
|
"",
|
|
75
|
-
"Top recommendations (ordered by priority):",
|
|
62
|
+
planLines ? "Editing recommendations (report order):" : "Top recommendations (ordered by priority):",
|
|
76
63
|
"",
|
|
77
|
-
...recs.lines,
|
|
78
|
-
recs.truncationNote ? "" : null,
|
|
79
|
-
recs.truncationNote,
|
|
64
|
+
...(planLines ?? recs.lines),
|
|
65
|
+
!planLines && recs.truncationNote ? "" : null,
|
|
66
|
+
planLines ? null : recs.truncationNote,
|
|
80
67
|
"",
|
|
81
68
|
opts.creditsRemaining !== null
|
|
82
69
|
? `Credits remaining after this call: ${opts.creditsRemaining}`
|
|
@@ -89,7 +76,7 @@ export function buildPhase1OnlyFromGetText(resource) {
|
|
|
89
76
|
const qs = formatQualitySignals(resource.qualitySignals);
|
|
90
77
|
return blank([
|
|
91
78
|
`Analysis ID: ${resource.analysisId}`,
|
|
92
|
-
"Status: Phase 1
|
|
79
|
+
"Status: Phase 1 result available — Phase 2 completion is not confirmed.",
|
|
93
80
|
`URL: ${URL_NOT_AVAILABLE}`,
|
|
94
81
|
`Full report: ${reportUrlFor(resource.analysisId)} — ${FULL_REPORT_HINT}.`,
|
|
95
82
|
`Primary Retrieval Role: ${resource.context.primaryRetrievalRole}`,
|
|
@@ -102,6 +89,6 @@ export function buildPhase1OnlyFromGetText(resource) {
|
|
|
102
89
|
"",
|
|
103
90
|
`Quality signals: ${qs}`,
|
|
104
91
|
"",
|
|
105
|
-
`
|
|
92
|
+
`If Phase 2 was never requested, call complete_analysis with this analysisId (costs 1 credit). If a previous call was interrupted, this response does not establish execution or credit settlement status. Wait and check the same ID again, or open the report in the web app for recovery status.`,
|
|
106
93
|
]);
|
|
107
94
|
}
|
package/dist/progress.js
CHANGED
|
@@ -21,12 +21,7 @@ export function startProgressTicker(opts) {
|
|
|
21
21
|
}
|
|
22
22
|
})());
|
|
23
23
|
}, intervalMs);
|
|
24
|
-
return () =>
|
|
25
|
-
clearInterval(interval);
|
|
26
|
-
if (opts.doneMessage !== undefined) {
|
|
27
|
-
void sendProgressNow(opts.send, opts.progressToken, opts.doneMessage, progress + 1);
|
|
28
|
-
}
|
|
29
|
-
};
|
|
24
|
+
return () => clearInterval(interval);
|
|
30
25
|
}
|
|
31
26
|
export async function sendProgressNow(send, progressToken, message, progress) {
|
|
32
27
|
if (progressToken === undefined || progressToken === null)
|
package/dist/server.js
CHANGED
|
@@ -55,7 +55,7 @@ const TOOLS = [
|
|
|
55
55
|
description: ANALYZE_URL_PHASE1_DESC,
|
|
56
56
|
inputSchema: {
|
|
57
57
|
type: "object",
|
|
58
|
-
properties: { url: URL_PROP, audience: AUDIENCE_PROP_PHASE1 },
|
|
58
|
+
properties: { url: URL_PROP, audience: AUDIENCE_PROP_PHASE1, includeSource: { type: "boolean", description: "Return the exact analyzed extraction in this response for optional transfer to complete_analysis. Omitted by default; not saved as a report field." } },
|
|
59
59
|
required: ["url"],
|
|
60
60
|
},
|
|
61
61
|
annotations: {
|
|
@@ -73,6 +73,7 @@ const TOOLS = [
|
|
|
73
73
|
properties: {
|
|
74
74
|
analysisId: ANALYSIS_ID_PROP_FOR_COMPLETE,
|
|
75
75
|
audience: AUDIENCE_PROP_PHASE2,
|
|
76
|
+
sourceText: { type: "string", minLength: 1, maxLength: 80029, description: "Optional exact sourceText returned by analyze_url_phase1 with includeSource. The server verifies it against the owned analysis before charging. Do not edit or reconstruct it." },
|
|
76
77
|
},
|
|
77
78
|
required: ["analysisId"],
|
|
78
79
|
},
|
|
@@ -157,12 +158,14 @@ export function createServer(opts) {
|
|
|
157
158
|
case "analyze_url_phase1":
|
|
158
159
|
result = await runAnalyzeUrlPhase1({
|
|
159
160
|
url: String(args.url ?? ""),
|
|
161
|
+
includeSource: args.includeSource,
|
|
160
162
|
audience: typeof args.audience === "string" ? args.audience : undefined,
|
|
161
163
|
}, ctx);
|
|
162
164
|
break;
|
|
163
165
|
case "complete_analysis":
|
|
164
166
|
result = await runCompleteAnalysis({
|
|
165
167
|
analysisId: String(args.analysisId ?? ""),
|
|
168
|
+
sourceText: args.sourceText,
|
|
166
169
|
audience: typeof args.audience === "string" ? args.audience : undefined,
|
|
167
170
|
}, ctx);
|
|
168
171
|
break;
|
|
@@ -12,26 +12,31 @@ export async function runAnalyzeUrlPhase1(args, ctx) {
|
|
|
12
12
|
if (args.audience !== undefined && args.audience.length > 500) {
|
|
13
13
|
return errorResult(AUDIENCE_TOO_LONG);
|
|
14
14
|
}
|
|
15
|
+
if (args.includeSource !== undefined && typeof args.includeSource !== "boolean")
|
|
16
|
+
return errorResult("includeSource must be a boolean.");
|
|
15
17
|
try {
|
|
16
18
|
return await withSemaphore(sharedSemaphore, async () => {
|
|
17
19
|
const stop = startProgressTicker({
|
|
18
20
|
progressToken: ctx.progressToken,
|
|
19
21
|
send: ctx.sendProgress,
|
|
20
22
|
message: (s) => `Phase 1 in progress — building concept map. Elapsed: ${s}s. Typical: 30-60s, worst case: ~290s.`,
|
|
21
|
-
doneMessage: "Phase 1 complete.",
|
|
22
23
|
});
|
|
23
24
|
try {
|
|
24
25
|
const phase1 = await ctx.client.createPhase1({
|
|
25
26
|
url: args.url,
|
|
26
27
|
audience: args.audience,
|
|
28
|
+
...(args.includeSource !== undefined ? { includeSource: args.includeSource } : {}),
|
|
27
29
|
}, "analyze_url_phase1");
|
|
30
|
+
const publicPhase1 = { ...phase1 };
|
|
31
|
+
if (!args.includeSource)
|
|
32
|
+
delete publicPhase1.sourceText;
|
|
28
33
|
const text = buildPhase1Text({
|
|
29
34
|
url: args.url,
|
|
30
35
|
audience: args.audience,
|
|
31
|
-
resource:
|
|
36
|
+
resource: publicPhase1,
|
|
32
37
|
});
|
|
33
38
|
return {
|
|
34
|
-
content: [textItem(text), analysisResource(phase1.analysisId,
|
|
39
|
+
content: [textItem(text), analysisResource(phase1.analysisId, publicPhase1)],
|
|
35
40
|
};
|
|
36
41
|
}
|
|
37
42
|
finally {
|
|
@@ -36,13 +36,13 @@ export async function runAnalyzeUrl(args, ctx) {
|
|
|
36
36
|
progressToken: ctx.progressToken,
|
|
37
37
|
send: ctx.sendProgress,
|
|
38
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
39
|
});
|
|
41
40
|
let phase1;
|
|
42
41
|
try {
|
|
43
42
|
phase1 = await ctx.client.createPhase1({
|
|
44
43
|
url: args.url,
|
|
45
44
|
audience: args.audience,
|
|
45
|
+
includeSource: true,
|
|
46
46
|
}, "analyze_url");
|
|
47
47
|
}
|
|
48
48
|
finally {
|
|
@@ -56,12 +56,12 @@ export async function runAnalyzeUrl(args, ctx) {
|
|
|
56
56
|
progressToken: ctx.progressToken,
|
|
57
57
|
send: ctx.sendProgress,
|
|
58
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
59
|
});
|
|
61
60
|
let phase2;
|
|
62
61
|
try {
|
|
63
62
|
phase2 = await ctx.client.completePhase2(phase1.analysisId, {
|
|
64
63
|
audience: args.audience,
|
|
64
|
+
...(phase1.sourceText !== undefined ? { sourceText: phase1.sourceText } : {}),
|
|
65
65
|
}, "analyze_url");
|
|
66
66
|
}
|
|
67
67
|
finally {
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { effectiveAudience } from '../formatters/accepted-plan.js';
|
|
1
2
|
import { getCachedCredits, setCachedCredits, } from "../credit-cache.js";
|
|
2
3
|
import { ApiError } from "../errors.js";
|
|
3
4
|
import { buildPhase2Text } from "../formatters/analysis-text.js";
|
|
@@ -15,6 +16,8 @@ export async function runCompleteAnalysis(args, ctx) {
|
|
|
15
16
|
if (args.audience !== undefined && args.audience.length > 500) {
|
|
16
17
|
return errorResult(AUDIENCE_TOO_LONG);
|
|
17
18
|
}
|
|
19
|
+
if (args.sourceText !== undefined && (typeof args.sourceText !== "string" || args.sourceText.length === 0 || args.sourceText.length > 80029))
|
|
20
|
+
return errorResult("sourceText must be the exact nonempty analyzed extraction, at most 80029 characters.");
|
|
18
21
|
let existing;
|
|
19
22
|
try {
|
|
20
23
|
existing = await ctx.client.getAnalysis(args.analysisId, "complete_analysis");
|
|
@@ -26,7 +29,18 @@ export async function runCompleteAnalysis(args, ctx) {
|
|
|
26
29
|
return toolErrorFromException(err, { analysisId: args.analysisId });
|
|
27
30
|
}
|
|
28
31
|
if (existing.status === "complete") {
|
|
29
|
-
|
|
32
|
+
if (args.audience !== undefined && args.audience.trim() !== effectiveAudience(existing))
|
|
33
|
+
return errorResult("This saved report has a different audience or unknown audience provenance. Read it without an audience override, or start a new analysis. No credit was charged.");
|
|
34
|
+
let phase2 = existing;
|
|
35
|
+
if (args.sourceText !== undefined) {
|
|
36
|
+
try {
|
|
37
|
+
// A completed POST verifies the owned source fingerprint and remains free.
|
|
38
|
+
phase2 = await withSemaphore(sharedSemaphore, () => ctx.client.completePhase2(args.analysisId, { audience: args.audience, sourceText: args.sourceText }, "complete_analysis"));
|
|
39
|
+
}
|
|
40
|
+
catch (err) {
|
|
41
|
+
return toolErrorFromException(err, { analysisId: args.analysisId });
|
|
42
|
+
}
|
|
43
|
+
}
|
|
30
44
|
const text = buildPhase2Text({
|
|
31
45
|
audience: args.audience,
|
|
32
46
|
resource: phase2,
|
|
@@ -55,11 +69,11 @@ export async function runCompleteAnalysis(args, ctx) {
|
|
|
55
69
|
progressToken: ctx.progressToken,
|
|
56
70
|
send: ctx.sendProgress,
|
|
57
71
|
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
72
|
});
|
|
60
73
|
try {
|
|
61
74
|
const phase2 = await ctx.client.completePhase2(args.analysisId, {
|
|
62
75
|
audience: args.audience,
|
|
76
|
+
...(args.sourceText !== undefined ? { sourceText: args.sourceText } : {}),
|
|
63
77
|
}, "complete_analysis");
|
|
64
78
|
let creditsAfter = null;
|
|
65
79
|
try {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@contentgrapher-io/mcp-server",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.2",
|
|
4
4
|
"description": "MCP server for ContentGrapher: structural completeness analysis for web content. Wraps ContentGrapher REST API v1.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -46,10 +46,10 @@
|
|
|
46
46
|
],
|
|
47
47
|
"repository": {
|
|
48
48
|
"type": "git",
|
|
49
|
-
"url": "git+https://github.com/
|
|
49
|
+
"url": "git+https://github.com/danielkcheung/mcp-server.git"
|
|
50
50
|
},
|
|
51
51
|
"bugs": {
|
|
52
|
-
"url": "https://github.com/
|
|
52
|
+
"url": "https://github.com/danielkcheung/mcp-server/issues"
|
|
53
53
|
},
|
|
54
|
-
"homepage": "https://contentgrapher.io/
|
|
54
|
+
"homepage": "https://www.contentgrapher.io/help"
|
|
55
55
|
}
|