EDINET APIをMCP化する設計：書類検索・取得・XBRL抽出の3ツールとキー管理・出典保持

{
  "mcpServers": {
    "edinet": {
      "command": "node",
      "args": ["/absolute/path/edinet-mcp/dist/server.js"],
      "env": { "EDINET_API_KEY": "${EDINET_API_KEY}" }
    }
  }
}

import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

// ---- 環境変数からキーを読む。ツール入出力には出さない ----
const API_KEY = process.env.EDINET_API_KEY;
if (!API_KEY) {
  console.error('EDINET_API_KEY が未設定です');
  process.exit(1);
}
const API_BASE = 'https://api.edinet-fsa.go.jp/api/v2';
const maskKey = (url: string) => url.replace(/Subscription-Key=[^&]*/g, 'Subscription-Key=***');

// ---- 書類一覧 API の results 1件（仕様書 3-1-2-2、40項目のうち設計で使うもの） ----
type EdinetDocument = {
  seqNumber: number;
  docID: string;
  edinetCode: string | null;
  secCode: string | null;
  JCN: string | null;
  filerName: string | null;
  ordinanceCode: string | null;
  formCode: string | null;
  docTypeCode: string | null;
  periodStart: string | null;
  periodEnd: string | null;
  submitDateTime: string | null;
  docDescription: string | null;
  parentDocID: string | null;
  withdrawalStatus: '0' | '1' | '2';
  docInfoEditStatus: '0' | '1' | '2';
  disclosureStatus: '0' | '1' | '2' | '3';
  xbrlFlag: '0' | '1';
  pdfFlag: '0' | '1';
  attachDocFlag: '0' | '1';
  englishDocFlag: '0' | '1';
  csvFlag: '0' | '1';
  legalStatus: '0' | '1' | '2';
};

// ---- 出典（mcp-source-provenance-schema の形 + EDINET 固有の時点情報） ----
const SourceSchema = z.object({
  id: z.string().length(8).describe('docID'),
  uri: z.string().describe('キーを含まない URL'),
  title: z.string(),
  publisher: z.literal('金融庁 EDINET'),
  retrievedAt: z.string(),
  sourceType: z.enum(['official-api', 'document']),
  submitDateTime: z.string().nullable(),
  periodStart: z.string().nullable(),
  periodEnd: z.string().nullable(),
  parentDocID: z.string().nullable(),
  contentHash: z.string().regex(/^sha256:[0-9a-f]{64}$/).optional(),
});
const ProvenanceSchema = z.object({
  generatedAt: z.string(),
  sources: z.array(SourceSchema).min(1),
  transformations: z.array(z.object({ type: z.enum(['extract', 'filter', 'normalize']), description: z.string() })),
  warnings: z.array(z.string()),
});

const DocumentSummarySchema = z.object({
  docID: z.string(),
  filerName: z.string().nullable(),
  edinetCode: z.string().nullable(),
  secCode: z.string().nullable(),
  docTypeCode: z.string().nullable(),
  docDescription: z.string().nullable(),
  periodStart: z.string().nullable(),
  periodEnd: z.string().nullable(),
  submitDateTime: z.string().nullable(),
  parentDocID: z.string().nullable(),
  withdrawalStatus: z.string(),
  disclosureStatus: z.string(),
  legalStatus: z.string(),
  available: z.object({ xbrl: z.boolean(), pdf: z.boolean(), csv: z.boolean(), english: z.boolean() }),
});

// ---- 索引・取得・抽出は別モジュール（未実装） ----
interface DocumentIndex {
  search(q: { edinetCode?: string; secCode?: string; docTypeCode: string;
              periodEndFrom?: string; periodEndTo?: string; includeAmendments: boolean }): Promise<EdinetDocument[]>;
}
declare const index: DocumentIndex; // TODO: 日次で documents.json?type=2 を取り込む索引

serveStdio(() => {
  const server = new McpServer({ name: 'edinet', version: '0.0.1' });

  server.registerTool(
    'search_documents',
    {
      title: 'EDINET 書類検索（ローカル索引）',
      description: '日次取り込み済みの提出書類一覧から候補を返す。既定は有価証券報告書（docTypeCode=120）。' +
        '訂正報告書（130）は includeAmendments=true で含める。書類本体は fetch_document で取得する。',
      inputSchema: z.object({
        edinetCode: z.string().length(6).optional(),
        secCode: z.string().length(5).optional(),
        docTypeCode: z.string().length(3).default('120'),
        periodEndFrom: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
        periodEndTo: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
        includeAmendments: z.boolean().default(false),
        limit: z.number().int().min(1).max(50).default(10),
      }),
      outputSchema: z.object({
        data: z.object({ items: z.array(DocumentSummarySchema), indexedThrough: z.string().describe('索引が反映済みのファイル日付') }),
        provenance: ProvenanceSchema,
      }),
      annotations: { readOnlyHint: true },
    },
    async (input) => {
      // TODO: index.search() を呼び、withdrawalStatus=2 / disclosureStatus=2 / legalStatus=0 を warnings 付きで区別して返す
      throw new Error('not implemented');
    },
  );

  server.registerTool(
    'fetch_document',
    {
      title: 'EDINET 書類取得',
      description: 'docID と type（1: 本文+監査報告書 ZIP, 2: PDF, 3: 添付 ZIP, 4: 英文 ZIP, 5: CSV ZIP）で書類本体を保存し、' +
        'パス・Content-Type・サイズ・SHA-256 を返す。本文そのものは返さない。',
      inputSchema: z.object({
        docID: z.string().length(8),
        type: z.enum(['1', '2', '3', '4', '5']).default('1'),
      }),
      outputSchema: z.object({
        data: z.object({
          docID: z.string(), type: z.string(), savedPath: z.string(),
          contentType: z.string(), bytes: z.number(), sha256: z.string(),
        }).nullable(),
        provenance: ProvenanceSchema,
      }),
      annotations: { readOnlyHint: true, openWorldHint: true },
    },
    async ({ docID, type }) => {
      const url = `${API_BASE}/documents/${docID}?type=${type}&Subscription-Key=${API_KEY}`;
      // TODO: fetch(url) → Content-Type が application/json なら失敗（本文の StatusCode/metadata.status を読む）
      //       application/octet-stream / application/pdf なら保存し SHA-256 を計算
      //       provenance.sources[].uri には maskKey(url) ではなく閲覧サイトの書類URLかパス部分だけを入れる
      //       429 は再試行せず warnings に載せて返す
      void maskKey(url);
      throw new Error('not implemented');
    },
  );

  server.registerTool(
    'extract_facts',
    {
      title: 'EDINET 財務項目抽出',
      description: '保存済みの CSV（type=5）または XBRL（type=1）から、許可リスト内の項目だけを値・単位・期間付きで返す。',
      inputSchema: z.object({
        docID: z.string().length(8),
        concepts: z.array(z.string()).min(1).max(50).describe('許可リスト内の項目名'),
        consolidated: z.boolean().default(true),
      }),
      outputSchema: z.object({
        data: z.object({
          facts: z.array(z.object({
            concept: z.string(), value: z.string(), unit: z.string().nullable(),
            periodStart: z.string().nullable(), periodEnd: z.string().nullable(),
            consolidated: z.boolean(), sourceRefs: z.array(z.string()),
          })),
          notFound: z.array(z.string()),
        }),
        provenance: ProvenanceSchema,
      }),
      annotations: { readOnlyHint: true },
    },
    async () => {
      // TODO: CSV レイアウトは「書類閲覧操作ガイド」で確認してから実装する（本記事では未確認）
      throw new Error('not implemented');
    },
  );

  console.error('edinet MCP server listening on stdio');
  return server;
});