Stock MCP Server

{ "openapi": "3.0.3", "info": { "title": "Stock MCP - Filings API", "description": "API for fetching and processing SEC filings (US) and A-share announcements (China)", "version": "1.0.0", "contact": { "name": "ValueCell", "email": "support@valuecell.com" } }, "servers": [ { "url": "http://localhost:9898/api/v1", "description": "Local development server" } ], "tags": [ { "name": "SEC Filings", "description": "US SEC filings (10-K, 10-Q, 8-K, etc.)" }, { "name": "A-Share Filings", "description": "China A-share announcements and reports" }, { "name": "Document Processing", "description": "Document download, conversion, and caching" } ], "paths": { "/filings/sec/periodic": { "get": { "tags": ["SEC Filings"], "summary": "Get SEC periodic filings", "description": "Fetch SEC periodic filings (10-K annual reports, 10-Q quarterly reports) for a given US stock ticker.", "operationId": "getPeriodicSecFilings", "parameters": [ { "name": "ticker", "in": "query", "required": true, "description": "US stock ticker symbol (e.g., AAPL, MSFT, GOOGL)", "schema": { "type": "string", "example": "AAPL" } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year to filter", "schema": { "type": "integer", "example": 2024 } }, { "name": "quarter", "in": "query", "required": false, "description": "Fiscal quarter (1-4)", "schema": { "type": "integer", "minimum": 1, "maximum": 4, "example": 1 } }, { "name": "forms", "in": "query", "required": false, "description": "Filing forms to filter (e.g., 10-K, 10-Q)", "schema": { "type": "array", "items": { "type": "string" }, "example": ["10-K", "10-Q"] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "List of SEC periodic filings", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecFiling" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/filings/sec/event": { "get": { "tags": ["SEC Filings"], "summary": "Get SEC event-driven filings", "description": "Fetch SEC event-driven filings (8-K current reports, 6-K foreign filings) for a given US stock ticker.", "operationId": "getEventSecFilings", "parameters": [ { "name": "ticker", "in": "query", "required": true, "description": "US stock ticker symbol", "schema": { "type": "string", "example": "AAPL" } }, { "name": "start_date", "in": "query", "required": false, "description": "Start date for filtering (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "End date for filtering (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "forms", "in": "query", "required": false, "description": "Filing forms to filter (e.g., 8-K, 6-K)", "schema": { "type": "array", "items": { "type": "string" }, "example": ["8-K"] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "List of SEC event filings", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecFiling" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/filings/ashare": { "get": { "tags": ["A-Share Filings"], "summary": "Get A-share filings", "description": "Fetch A-share announcements and reports from SSE/SZSE exchanges.", "operationId": "getAshareFilings", "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "A-share stock symbol (e.g., 600519 for Moutai)", "schema": { "type": "string", "example": "600519" } }, { "name": "filing_types", "in": "query", "required": false, "description": "Report types to filter (annual, quarterly)", "schema": { "type": "array", "items": { "type": "string" }, "example": ["annual", "quarterly"] } }, { "name": "start_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "List of A-share filings", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AshareFiling" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/filings/markdown": { "get": { "tags": ["Document Processing"], "summary": "Get filing content as Markdown", "description": "Get SEC filing content converted to Markdown format. Supports MinIO caching for fast subsequent requests. First request fetches from SEC and caches; subsequent requests return cached content instantly.", "operationId": "getFilingMarkdown", "parameters": [ { "name": "ticker", "in": "query", "required": true, "description": "Stock ticker with optional exchange prefix (e.g., AAPL or NASDAQ:AAPL)", "schema": { "type": "string", "example": "AAPL" } }, { "name": "doc_id", "in": "query", "required": true, "description": "SEC Accession Number (e.g., 0000320193-25-000079)", "schema": { "type": "string", "example": "0000320193-25-000079" } }, { "name": "stream", "in": "query", "required": false, "description": "If true, return plain text Markdown; otherwise return JSON with metadata", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Filing content as Markdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownResponse" } }, "text/markdown": { "schema": { "type": "string", "description": "Raw Markdown content (when stream=true)" } } }, "headers": { "X-Cached": { "description": "Whether the response was served from cache", "schema": { "type": "string", "example": "True" } }, "X-Doc-Id": { "description": "Document ID", "schema": { "type": "string" } }, "X-Ticker": { "description": "Ticker symbol", "schema": { "type": "string" } } } }, "404": { "description": "Filing not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/filings/process": { "post": { "tags": ["Document Processing"], "summary": "Process a document", "description": "Download a document from URL, clean/convert it, and upload to MinIO storage.", "operationId": "processDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentRequest" } } } }, "responses": { "200": { "description": "Document processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentResponse" } } } }, "500": { "description": "Processing failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/filings/chunks": { "get": { "tags": ["Document Processing"], "summary": "Get SEC filing semantic chunks", "description": "Get SEC filing content as semantic chunks with item labels. Uses edgartools' ChunkedDocument for intelligent chunking based on document structure. Each chunk includes rich metadata for precise RAG filtering.", "operationId": "getDocumentChunks", "parameters": [ { "name": "ticker", "in": "query", "required": true, "description": "Stock ticker with optional exchange prefix (e.g., AAPL or NASDAQ:AAPL)", "schema": { "type": "string", "example": "AAPL" } }, { "name": "doc_id", "in": "query", "required": true, "description": "SEC Accession Number (e.g., 0000320193-25-000079)", "schema": { "type": "string", "example": "0000320193-25-000079" } }, { "name": "items", "in": "query", "required": false, "description": "Optional list of items to extract (e.g., Item 1A, Item 7). Defaults to [Item 1, Item 1A, Item 7, Item 7A, Item 8]", "schema": { "type": "array", "items": { "type": "string" }, "example": ["Item 1A", "Item 7", "Item 8"] } } ], "responses": { "200": { "description": "Document chunks with metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChunksResponse" } } } }, "404": { "description": "Filing not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "SecFiling": { "type": "object", "description": "SEC filing metadata", "properties": { "accession_number": { "type": "string", "description": "SEC Accession Number (unique identifier)", "example": "0000320193-25-000079" }, "form": { "type": "string", "description": "Filing form type", "example": "10-K" }, "filing_date": { "type": "string", "format": "date", "description": "Date the filing was submitted", "example": "2024-11-01" }, "symbol": { "type": "string", "description": "Stock ticker symbol", "example": "AAPL" }, "company_name": { "type": "string", "description": "Company name", "example": "Apple Inc." }, "description": { "type": "string", "description": "Filing description", "example": "Annual Report" }, "filing_url": { "type": "string", "format": "uri", "description": "URL to the filing on SEC EDGAR", "example": "https://www.sec.gov/Archives/edgar/data/320193/..." }, "primary_document": { "type": "string", "description": "Primary document filename", "example": "aapl-20240928.htm" } } }, "AshareFiling": { "type": "object", "description": "A-share filing/announcement metadata", "properties": { "filing_id": { "type": "string", "description": "Unique filing identifier (from cninfo.com.cn)", "example": "1219506510" }, "symbol": { "type": "string", "description": "Stock symbol", "example": "600519" }, "company_name": { "type": "string", "description": "Company name in Chinese", "example": "贵州茅台" }, "exchange": { "type": "string", "description": "Exchange (SSE=Shanghai, SZSE=Shenzhen)", "enum": ["SSE", "SZSE"], "example": "SSE" }, "title": { "type": "string", "description": "Filing title", "example": "贵州茅台2023年年度报告" }, "type": { "type": "string", "description": "Filing type (may be empty)", "example": "" }, "form": { "type": "string", "description": "Form type (may be empty)", "example": "" }, "filing_date": { "type": "string", "format": "date", "description": "Filing date", "example": "2024-04-03" }, "period_of_report": { "type": "string", "description": "Reporting period", "example": "2024" }, "url": { "type": "string", "format": "uri", "description": "URL to the PDF document", "example": "http://static.cninfo.com.cn/finalpage/2024-04-03/1219506510.PDF" }, "content_summary": { "type": "string", "description": "Brief summary of the filing content", "example": "贵州茅台2023年年度报告" } } }, "MarkdownResponse": { "type": "object", "description": "Markdown content response with metadata", "properties": { "status": { "type": "string", "enum": ["success", "error"], "example": "success" }, "cached": { "type": "boolean", "description": "Whether the content was returned from cache", "example": true }, "content": { "type": "string", "description": "Markdown content of the filing", "example": "# 10-K Filing: AAPL (2024-11-01)\n\n## Main Document\n..." }, "doc_id": { "type": "string", "description": "Document ID", "example": "0000320193-25-000079" }, "ticker": { "type": "string", "description": "Stock ticker", "example": "AAPL" }, "form_type": { "type": "string", "description": "Filing form type", "example": "10-K" }, "filing_date": { "type": "string", "description": "Filing date", "example": "2024-11-01" } } }, "ProcessDocumentRequest": { "type": "object", "required": ["doc_id", "url", "doc_type"], "properties": { "doc_id": { "type": "string", "description": "Document identifier", "example": "0000320193-25-000079" }, "url": { "type": "string", "format": "uri", "description": "URL to download the document from", "example": "https://www.sec.gov/Archives/edgar/data/320193/..." }, "doc_type": { "type": "string", "description": "Document type (SEC, PDF, etc.)", "example": "SEC" }, "ticker": { "type": "string", "description": "Stock ticker (optional)", "example": "AAPL" } } }, "ProcessDocumentResponse": { "type": "object", "properties": { "doc_id": { "type": "string", "description": "Document identifier" }, "status": { "type": "string", "enum": ["success", "failed", "error"], "description": "Processing status" }, "storage_path": { "type": "string", "description": "Path where the document was stored in MinIO" }, "file_size": { "type": "integer", "description": "Size of the processed file in bytes" }, "error": { "type": "string", "description": "Error message if processing failed" } } }, "Error": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message", "example": "Filing not found for ticker: AAPL" } } }, "ChunksResponse": { "type": "object", "description": "Response containing document chunks with metadata", "properties": { "status": { "type": "string", "enum": ["success", "error"], "example": "success" }, "doc_id": { "type": "string", "description": "SEC Accession Number", "example": "0000320193-24-000123" }, "ticker": { "type": "string", "description": "Stock ticker", "example": "AAPL" }, "form": { "type": "string", "description": "Filing form type", "example": "10-K" }, "filing_date": { "type": "string", "description": "Filing date", "example": "2024-11-01" }, "chunks_count": { "type": "integer", "description": "Total number of chunks", "example": 150 }, "fallback": { "type": "boolean", "description": "Whether fallback chunking was used", "example": false }, "chunks": { "type": "array", "description": "List of document chunks", "items": { "$ref": "#/components/schemas/DocumentChunk" } }, "error": { "type": "string", "description": "Error message if status is error" } }, "required": ["status"] }, "DocumentChunk": { "type": "object", "description": "A semantic chunk from a SEC filing", "properties": { "text": { "type": "string", "description": "The chunk content text", "example": "Risk factors include competition in the technology industry..." }, "metadata": { "$ref": "#/components/schemas/ChunkMetadata" } }, "required": ["text", "metadata"] }, "ChunkMetadata": { "type": "object", "description": "Metadata for a document chunk", "properties": { "ticker": { "type": "string", "description": "Stock ticker", "example": "AAPL" }, "doc_id": { "type": "string", "description": "SEC Accession Number", "example": "0000320193-24-000123" }, "form": { "type": "string", "description": "Filing form type", "example": "10-K" }, "item": { "type": "string", "description": "SEC Item section (e.g., Item 1A for Risk Factors)", "example": "Item 1A" }, "item_name": { "type": "string", "description": "Human-readable item name", "example": "Risk Factors" }, "filing_date": { "type": "string", "description": "Filing date", "example": "2024-11-01" }, "chunk_index": { "type": "integer", "description": "Global chunk index in the document", "example": 5 }, "item_chunk_index": { "type": "integer", "description": "Chunk index within the item section", "example": 2 } } } } } }