@shuji-bonji/pdf-spec-mcp 0.3.1 → 0.4.1

package/README.ja.md

@@ -165,12 +165,12 @@ pdf-specs/
 ### 2. インストール
 
 このパッケージは MCP クライアントから起動される CLI バイナリ（`pdf-spec-mcp`）を提供します。
-**通常は手動でインストールする必要はありません** — 次のステップのように MCP クライアント側で `npx @shuji-bonji/pdf-spec-mcp` を指定してください。
+**通常は手動でインストールする必要はありません** — 次のステップのように MCP クライアント側で `npx @shuji-bonji/pdf-spec-mcp@latest` を指定してください。
 
 シェルから直接動作確認したい場合（デバッグ用途など）:
 
 ```bash
-PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp
+PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latest
 ```
 
 グローバルインストールしたい場合（任意）:
@@ -197,7 +197,7 @@ PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp
   "mcpServers": {
     "pdf-spec": {
       "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-spec-mcp"],
+      "args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
       "env": {
         "PDF_SPEC_DIR": "/path/to/pdf-specs"
       }
@@ -206,6 +206,13 @@ PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp
 }
 ```
 
+> [!IMPORTANT]
+> **`@latest` を付ける（またはバージョンを固定する）。** バージョン指定なしの `npx -y <pkg>` は
+> **最初にキャッシュしたものを使い続ける** — `-y` はインストールの確認を省くだけで、更新は確認しない。
+> 指定なしだと数ヶ月前のリリースが動き続けることがある。`@latest` を付けると npx が起動のたびに
+> レジストリを確認する。再現性が要るなら `@0.4.0` のように固定する。
+> 古いキャッシュを消すには `rm -rf ~/.npm/_npx`。
+
 #### Cursor / VS Code
 
 `.cursor/mcp.json` または VS Code の MCP 設定に追加：
@@ -215,7 +222,7 @@ PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp
   "mcpServers": {
     "pdf-spec": {
       "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-spec-mcp"],
+      "args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
       "env": {
         "PDF_SPEC_DIR": "/path/to/pdf-specs"
       }

package/README.md

@@ -165,12 +165,12 @@ pdf-specs/
 ### 2. Install
 
 This package ships a CLI binary (`pdf-spec-mcp`) intended to be launched by an MCP client.
-**You do not need to install it manually** — just point your MCP client to `npx @shuji-bonji/pdf-spec-mcp` as shown in the next step.
+**You do not need to install it manually** — just point your MCP client to `npx @shuji-bonji/pdf-spec-mcp@latest` as shown in the next step.
 
 If you want to run it directly from the shell (e.g. for debugging):
 
 ```bash
-PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp
+PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latest
 ```
 
 Or install it globally (optional):
@@ -197,7 +197,7 @@ Add to `claude_desktop_config.json`:
   "mcpServers": {
     "pdf-spec": {
       "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-spec-mcp"],
+      "args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
       "env": {
         "PDF_SPEC_DIR": "/path/to/pdf-specs"
       }
@@ -206,6 +206,13 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
+> [!IMPORTANT]
+> **Use `@latest` (or pin a version).** `npx -y <pkg>` without a version keeps running whatever
+> it cached the first time — `-y` only skips the install prompt, it does not check for updates.
+> A bare specifier will happily run a months-old release. `@latest` makes npx check the registry
+> on each start; pin `@0.4.0` instead if you want reproducibility.
+> To clear a stale cache: `rm -rf ~/.npm/_npx`.
+
 #### Cursor / VS Code
 
 Add to `.cursor/mcp.json` or VS Code MCP settings:
@@ -215,7 +222,7 @@ Add to `.cursor/mcp.json` or VS Code MCP settings:
   "mcpServers": {
     "pdf-spec": {
       "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-spec-mcp"],
+      "args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
       "env": {
         "PDF_SPEC_DIR": "/path/to/pdf-specs"
       }

package/dist/config.d.ts

@@ -35,6 +35,8 @@ export declare const VALIDATION_LIMITS: {
     };
     readonly defaultMaxResults: 10;
 };
+/** Matches a table caption paragraph ("Table 182 — Additional entries...") */
+export declare const TABLE_CAPTION_START_RE: RegExp;
 /** Concurrency limits for chunked parallel processing */
 export declare const CONCURRENCY: {
     /** Pages processed in parallel during search index build */
@@ -44,6 +46,26 @@ export declare const CONCURRENCY: {
     /** Pages processed in parallel during content extraction */
     readonly contentExtraction: 10;
 };
+/** A normative area this server cannot answer for. */
+export interface CoverageGap {
+    area: string;
+    standards: string[];
+    consequence: string;
+}
+/**
+ * Areas outside this server's corpus (S-2).
+ *
+ * family 規約 §2.0 routes implementation decisions through this server, which makes a
+ * silent gap dangerous: `search_spec("PDF/A conformance")` returns zero hits, and zero hits
+ * read exactly like "no such requirement". The most consequential answers this server gives
+ * are the ones it cannot give, so it has to say so.
+ *
+ * These are not "the file happens to be missing". There is no SPEC_PATTERNS entry for
+ * either standard, so the PDFs would not be indexed even if they were placed in
+ * PDF_SPEC_DIR. Closing a gap means adding a pattern here, not just a file — and then
+ * removing the entry below.
+ */
+export declare const COVERAGE_GAPS: CoverageGap[];
 /** Filename pattern → spec ID mapping rule */
 export interface SpecPattern {
     pattern: RegExp;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKrD,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;CAEf,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,uDAAuD;AACvD,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,wEAAwE;AACxE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAOpB,CAAC;AAEX,yDAAyD;AACzD,eAAO,MAAM,WAAW;IACtB,4DAA4D;;IAE5D,qEAAqE;;IAErE,4DAA4D;;CAEpD,CAAC;AAEX,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAwItC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKrD,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;CAEf,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,uDAAuD;AACvD,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,wEAAwE;AACxE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAOpB,CAAC;AAEX,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AAErD,yDAAyD;AACzD,eAAO,MAAM,WAAW;IACtB,4DAA4D;;IAE5D,qEAAqE;;IAErE,4DAA4D;;CAEpD,CAAC;AAEX,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAiBtC,CAAC;AAEF,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAwItC,CAAC"}

package/dist/config.js

@@ -1,7 +1,7 @@
 /**
  * Application Configuration
  */
-import { createRequire } from 'module';
+import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 export const PACKAGE_INFO = {
@@ -28,6 +28,8 @@ export const VALIDATION_LIMITS = {
     maxResultsRange: { min: 1, max: 50 },
     defaultMaxResults: 10,
 };
+/** Matches a table caption paragraph ("Table 182 — Additional entries...") */
+export const TABLE_CAPTION_START_RE = /^Table\s+\d+/;
 /** Concurrency limits for chunked parallel processing */
 export const CONCURRENCY = {
     /** Pages processed in parallel during search index build */
@@ -37,6 +39,35 @@ export const CONCURRENCY = {
     /** Pages processed in parallel during content extraction */
     contentExtraction: 10,
 };
+/**
+ * Areas outside this server's corpus (S-2).
+ *
+ * family 規約 §2.0 routes implementation decisions through this server, which makes a
+ * silent gap dangerous: `search_spec("PDF/A conformance")` returns zero hits, and zero hits
+ * read exactly like "no such requirement". The most consequential answers this server gives
+ * are the ones it cannot give, so it has to say so.
+ *
+ * These are not "the file happens to be missing". There is no SPEC_PATTERNS entry for
+ * either standard, so the PDFs would not be indexed even if they were placed in
+ * PDF_SPEC_DIR. Closing a gap means adding a pattern here, not just a file — and then
+ * removing the entry below.
+ */
+export const COVERAGE_GAPS = [
+    {
+        area: 'PDF/A — archival conformance',
+        standards: ['ISO 19005-1', 'ISO 19005-2', 'ISO 19005-3', 'ISO 19005-4'],
+        consequence: 'Requirements specific to PDF/A cannot be quoted or verified here. pdf-verify-mcp ' +
+            'validate_conformance with a "pdfa-*" flavour has no normative text to trace to in this ' +
+            'corpus. A search returning nothing is not evidence that no requirement exists.',
+    },
+    {
+        area: 'PAdES — signature profiles',
+        standards: ['ETSI EN 319 142-1', 'ETSI EN 319 142-2'],
+        consequence: 'Baseline signature levels (B-B / B-T / B-LT / B-LTA) are defined by ETSI, not by ' +
+            'ISO 32000-2. pdf-verify-mcp detect_pades_level cannot be checked against normative text ' +
+            'here. ISO 32000-2 §12.8 covers signatures in general and is available.',
+    },
+];
 /**
  * Ordered list of filename patterns for auto-discovery.
  * Array order = priority: when multiple files map to the same spec ID,

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -4,35 +4,99 @@
  * Structured error classes for consistent error handling across the MCP server.
  * Each error carries a `code` string for programmatic error identification.
  */
+/** A concrete step an agent can take to get past an error. */
+export interface NextAction {
+    action: string;
+    reason: string;
+}
+/**
+ * The family error contract (規約 §2.3).
+ *
+ * `code` alone tells an agent *what* went wrong; `hint` and `next_actions` tell it what to
+ * do about it, and `retryable` whether doing so is worth trying. Orchestration Skills read
+ * these to decide their next move instead of surfacing a dead end to the user.
+ *
+ * @see https://github.com/shuji-bonji/houki-research-skill/blob/main/docs/ERROR-CODES.md
+ */
+export interface SpecServiceError {
+    error: string;
+    code: string;
+    /** What the caller should understand about the failure. */
+    hint?: string;
+    /** Concrete next steps. */
+    next_actions?: NextAction[];
+    /** Whether a different argument or a fixed environment could make this succeed. */
+    retryable?: boolean;
+}
 /**
  * Base error class for all pdf-spec-mcp errors.
  */
 export declare class PDFSpecError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    readonly hint?: string;
+    readonly next_actions?: NextAction[];
+    readonly retryable?: boolean;
+    constructor(code: string, message: string, options?: {
+        hint?: string;
+        next_actions?: NextAction[];
+        retryable?: boolean;
+    });
 }
+type ErrorOptions = {
+    hint?: string;
+    next_actions?: NextAction[];
+    retryable?: boolean;
+};
 /**
  * Input validation errors (invalid parameters, out-of-range values, etc.)
+ *
+ * Always retryable: the caller controls the arguments.
  */
 export declare class ValidationError extends PDFSpecError {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 /**
  * Registry-related errors (spec not found, env var missing, discovery failure)
  */
 export declare class RegistryError extends PDFSpecError {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 /**
  * Content extraction errors (section not found, page access failure, parse errors)
  */
 export declare class ContentError extends PDFSpecError {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 /**
  * Tool prerequisite errors (required specs not available, missing dependencies)
+ *
+ * Not retryable as-is: the environment has to change first. `next_actions` carries what
+ * that change is, so an orchestrating Skill can tell the user precisely what to install
+ * rather than reporting a bare failure.
  */
 export declare class ToolPrerequisiteError extends PDFSpecError {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Shape an error for the MCP response (規約 §2.3).
+ *
+ * Optional members are omitted rather than set to undefined, so the JSON stays clean for
+ * whatever reads it.
+ */
+export declare function toStructuredError(error: unknown): SpecServiceError;
+/**
+ * Presets for the recurring dead ends.
+ *
+ * This server is useless without its corpus — the spec PDFs are copyrighted and cannot be
+ * shipped, so "the file is not there" is the normal first-run failure rather than an
+ * exceptional one. Saying exactly which file, and where to get it, is what turns that into
+ * something an agent can resolve.
+ */
+export declare const NEXT_ACTIONS: {
+    readonly setSpecDir: (envVar: string) => NextAction;
+    readonly downloadSpec: (file: string, url: string) => NextAction;
+    readonly listSpecs: () => NextAction;
+    readonly getStructure: () => NextAction;
+};
+export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,YAAY;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;gBAG3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO;CASpF;AAED,KAAK,YAAY,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAExF;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;CAIxD;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;CAIxD;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,YAAY;gBAChC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;CAIxD;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;CAIxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAYlE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;kCACF,MAAM,KAAG,UAAU;kCAMnB,MAAM,OAAO,MAAM,KAAG,UAAU;8BAItC,UAAU;iCAIP,UAAU;CAIpB,CAAC"}

package/dist/errors.js

@@ -9,18 +9,26 @@
  */
 export class PDFSpecError extends Error {
     code;
-    constructor(code, message) {
+    hint;
+    next_actions;
+    retryable;
+    constructor(code, message, options = {}) {
         super(message);
         this.name = 'PDFSpecError';
         this.code = code;
+        this.hint = options.hint;
+        this.next_actions = options.next_actions;
+        this.retryable = options.retryable;
     }
 }
 /**
  * Input validation errors (invalid parameters, out-of-range values, etc.)
+ *
+ * Always retryable: the caller controls the arguments.
  */
 export class ValidationError extends PDFSpecError {
-    constructor(message) {
-        super('VALIDATION_ERROR', message);
+    constructor(message, options = {}) {
+        super('VALIDATION_ERROR', message, { retryable: true, ...options });
         this.name = 'ValidationError';
     }
 }
@@ -28,8 +36,8 @@ export class ValidationError extends PDFSpecError {
  * Registry-related errors (spec not found, env var missing, discovery failure)
  */
 export class RegistryError extends PDFSpecError {
-    constructor(message) {
-        super('REGISTRY_ERROR', message);
+    constructor(message, options = {}) {
+        super('REGISTRY_ERROR', message, options);
         this.name = 'RegistryError';
     }
 }
@@ -37,18 +45,71 @@ export class RegistryError extends PDFSpecError {
  * Content extraction errors (section not found, page access failure, parse errors)
  */
 export class ContentError extends PDFSpecError {
-    constructor(message) {
-        super('CONTENT_ERROR', message);
+    constructor(message, options = {}) {
+        super('CONTENT_ERROR', message, options);
         this.name = 'ContentError';
     }
 }
 /**
  * Tool prerequisite errors (required specs not available, missing dependencies)
+ *
+ * Not retryable as-is: the environment has to change first. `next_actions` carries what
+ * that change is, so an orchestrating Skill can tell the user precisely what to install
+ * rather than reporting a bare failure.
  */
 export class ToolPrerequisiteError extends PDFSpecError {
-    constructor(message) {
-        super('PREREQUISITE_ERROR', message);
+    constructor(message, options = {}) {
+        super('PREREQUISITE_ERROR', message, { retryable: false, ...options });
         this.name = 'ToolPrerequisiteError';
     }
 }
+/**
+ * Shape an error for the MCP response (規約 §2.3).
+ *
+ * Optional members are omitted rather than set to undefined, so the JSON stays clean for
+ * whatever reads it.
+ */
+export function toStructuredError(error) {
+    if (error instanceof PDFSpecError) {
+        const out = { error: error.message, code: error.code };
+        if (error.hint)
+            out.hint = error.hint;
+        if (error.next_actions && error.next_actions.length > 0)
+            out.next_actions = error.next_actions;
+        if (error.retryable !== undefined)
+            out.retryable = error.retryable;
+        return out;
+    }
+    if (error instanceof Error) {
+        return { error: error.message, code: 'INTERNAL_ERROR' };
+    }
+    return { error: String(error), code: 'INTERNAL_ERROR' };
+}
+/**
+ * Presets for the recurring dead ends.
+ *
+ * This server is useless without its corpus — the spec PDFs are copyrighted and cannot be
+ * shipped, so "the file is not there" is the normal first-run failure rather than an
+ * exceptional one. Saying exactly which file, and where to get it, is what turns that into
+ * something an agent can resolve.
+ */
+export const NEXT_ACTIONS = {
+    setSpecDir: (envVar) => ({
+        action: `set_${envVar}`,
+        reason: `Set the ${envVar} environment variable to the directory holding the specification PDFs, ` +
+            'then restart the MCP server. The PDFs are copyrighted and are not distributed with this package.',
+    }),
+    downloadSpec: (file, url) => ({
+        action: 'download_spec_pdf',
+        reason: `Place "${file}" in PDF_SPEC_DIR. Download it from ${url}`,
+    }),
+    listSpecs: () => ({
+        action: 'call_list_specs',
+        reason: 'Call list_specs to see which specification PDFs are currently available.',
+    }),
+    getStructure: () => ({
+        action: 'call_get_structure',
+        reason: 'Call get_structure to see the available section numbers for this spec.',
+    }),
+};
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,YAAY;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,YAAY,OAAe;QACzB,KAAK,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -3,5 +3,5 @@
  * PDF Spec MCP Server
  * MCP server for structured understanding of ISO 32000 (PDF) specifications
  */
-export {};
+import './utils/stdout-guard.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAIH,OAAO,yBAAyB,CAAC"}

package/dist/index.js

@@ -3,52 +3,15 @@
  * PDF Spec MCP Server
  * MCP server for structured understanding of ISO 32000 (PDF) specifications
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+// MUST be the first import: installs the stdout guard before any dependency
+// (notably pdfjs-dist) is evaluated. See utils/stdout-guard.ts.
+import './utils/stdout-guard.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { tools } from './tools/definitions.js';
-import { toolHandlers } from './tools/handlers.js';
-import { PDFSpecError } from './errors.js';
 import { PACKAGE_INFO } from './config.js';
-const server = new Server({
-    name: PACKAGE_INFO.name,
-    version: PACKAGE_INFO.version,
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-// List tools
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools };
-});
-// Execute tool
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-        if (!(name in toolHandlers)) {
-            throw new Error(`Unknown tool: ${name}`);
-        }
-        // Type boundary: MCP SDK provides args as Record<string, unknown>.
-        // After validating the tool name, we cast args to match the handler's
-        // expected input — each handler validates its own arguments at runtime.
-        const handler = toolHandlers[name];
-        const result = await handler(args ?? {});
-        return {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const code = error instanceof PDFSpecError ? error.code : 'INTERNAL_ERROR';
-        return {
-            content: [{ type: 'text', text: JSON.stringify({ error: message, code }, null, 2) }],
-            isError: true,
-        };
-    }
-});
+import { buildServer } from './server.js';
 // Start server
 async function main() {
+    const server = buildServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`${PACKAGE_INFO.name} v${PACKAGE_INFO.version} started`);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAEnG,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAiB,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;IACE,IAAI,EAAE,YAAY,CAAC,IAAI;IACvB,OAAO,EAAE,YAAY,CAAC,OAAO;CAC9B,EACD;IACE,YAAY,EAAE;QACZ,KAAK,EAAE,EAAE;KACV;CACF,CACF,CAAC;AAEF,aAAa;AACb,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;IAC1D,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC,CAAC,CAAC;AAEH,eAAe;AACf,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;IAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAEjD,IAAI,CAAC;QACH,IAAI,CAAC,CAAC,IAAI,IAAI,YAAY,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QAED,mEAAmE;QACnE,sEAAsE;QACtE,wEAAwE;QACxE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAgB,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,MAAO,OAA4D,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC/F,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACnE,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,KAAK,YAAY,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAC3E,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YACpF,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,eAAe;AACf,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,IAAI,KAAK,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;AACzE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,4EAA4E;AAC5E,gEAAgE;AAChE,OAAO,yBAAyB,CAAC;AAEjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,eAAe;AACf,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,IAAI,KAAK,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;AACzE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * MCP server construction (A-4: McpServer + registerTool + Zod).
+ *
+ * Kept apart from index.ts so the server can be built without starting a stdio
+ * transport — `registry.test.ts` drives it over an in-memory transport to pin the
+ * external tool surface. index.ts is left as the entry point that wires it to stdio.
+ *
+ * Tools come from the definitions.ts registry rather than being registered by hand here,
+ * so "what this server exposes" is one list rather than a sequence of calls, and a tool
+ * defined without a handler fails loudly at startup instead of at first use.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Build the MCP server with all tools registered.
+ * Does not connect a transport — the caller decides how it is driven.
+ */
+export declare function buildServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOpE;;;GAGG;AACH,wBAAgB,WAAW,IAAI,SAAS,CA0CvC"}

package/dist/server.js

@@ -0,0 +1,59 @@
+/**
+ * MCP server construction (A-4: McpServer + registerTool + Zod).
+ *
+ * Kept apart from index.ts so the server can be built without starting a stdio
+ * transport — `registry.test.ts` drives it over an in-memory transport to pin the
+ * external tool surface. index.ts is left as the entry point that wires it to stdio.
+ *
+ * Tools come from the definitions.ts registry rather than being registered by hand here,
+ * so "what this server exposes" is one list rather than a sequence of calls, and a tool
+ * defined without a handler fails loudly at startup instead of at first use.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { PACKAGE_INFO } from './config.js';
+import { toStructuredError } from './errors.js';
+import { tools } from './tools/definitions.js';
+import { toolHandlers } from './tools/handlers.js';
+import { logger } from './utils/logger.js';
+/**
+ * Build the MCP server with all tools registered.
+ * Does not connect a transport — the caller decides how it is driven.
+ */
+export function buildServer() {
+    const server = new McpServer({
+        name: PACKAGE_INFO.name,
+        version: PACKAGE_INFO.version,
+    });
+    for (const tool of tools) {
+        const handler = toolHandlers[tool.name];
+        if (!handler) {
+            throw new Error(`No handler registered for tool: ${tool.name}`);
+        }
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.shape,
+            annotations: tool.annotations,
+        }, async (args) => {
+            try {
+                const result = await handler(args);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (error) {
+                // Report failures as an isError result rather than throwing: a thrown error
+                // reaches the client as an opaque protocol error, losing the code / hint /
+                // next_actions an agent needs to recover (規約 §2.3).
+                const structured = toStructuredError(error);
+                logger.error(tool.name, structured.error, error instanceof Error ? error : undefined);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAiB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,YAAY,CAAC,IAAI;QACvB,OAAO,EAAE,YAAY,CAAC,OAAO;KAC9B,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,IAAgB,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,KAAK;YACvB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,EACD,KAAK,EAAE,IAAa,EAAE,EAAE;YACtB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;gBACnC,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;iBAC5E,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,4EAA4E;gBAC5E,2EAA2E;gBAC3E,oDAAoD;gBACpD,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;gBAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBACtF,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;oBAC/E,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/services/compare-service.d.ts

@@ -11,7 +11,7 @@
  *
  * Results are cached — full comparison runs once, then filtered per request.
  */
-import type { SectionIndex, SectionMapping, UnmatchedSection, CompareVersionsResult } from '../types/index.js';
+import type { CompareVersionsResult, SectionIndex, SectionMapping, UnmatchedSection } from '../types/index.js';
 export interface FullCompareResult {
     matched: SectionMapping[];
     added: UnmatchedSection[];

package/dist/services/compare-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compare-service.d.ts","sourceRoot":"","sources":["../../src/services/compare-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAMD,qBAAa,cAAc;IAGb,OAAO,CAAC,aAAa;IAFjC,OAAO,CAAC,kBAAkB,CAA2C;gBAEjD,aAAa,EAAE;QAAE,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;KAAE;IAE7F;;;OAGG;IACG,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4CvE;;OAEG;YACW,mBAAmB;CAsFlC;AAMD,eAAO,MAAM,qBAAqB,gBAA0C,CAAC;AAM7E;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,mCAAmD,CAAC"}
+{"version":3,"file":"compare-service.d.ts","sourceRoot":"","sources":["../../src/services/compare-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,YAAY,EAEZ,cAAc,EACd,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAS3B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAMD,qBAAa,cAAc;IAGb,OAAO,CAAC,aAAa;IAFjC,OAAO,CAAC,kBAAkB,CAA2C;gBAEjD,aAAa,EAAE;QAAE,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;KAAE;IAE7F;;;OAGG;IACG,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4CvE;;OAEG;YACW,mBAAmB;CAsFlC;AAMD,eAAO,MAAM,qBAAqB,gBAA0C,CAAC;AAM7E;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,mCAAmD,CAAC"}