### Start MCP Server (npm script)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Starts the Node.js Express MCP server. This command should be run after all setup and offline pipelines are complete.

```bash
npm run start
```

--------------------------------

### Install Dependencies (npm)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Installs project dependencies using npm. This is the first step in setting up the project.

```bash
npm install
```

--------------------------------

### Configure Environment Variables (bash)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Copies the example environment file to a new file for configuration. Users need to fill in essential variables like DATABASE_URL, SEC_USER_AGENT, and optionally OPENAI_API_KEY and FMP_API_KEY.

```bash
cp .env.example .env
```

--------------------------------

### Starting the MCP Server and Tool Calls (Bash)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Details how to start the Express server for the MCP project in both production and development modes. It also shows example `curl` commands to interact with the server's `/mcp` endpoint using the JSON-RPC 2.0 protocol to list available tools. The response format for listing tools is also indicated.

```bash
# Start server (production)
npm run start

# Start with auto-reload (development)
npm run dev

# Server listens on configured port (default 3000)
# MCP endpoint: POST http://localhost:3000/mcp

# Example: List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

# Response includes:
# - sec_latest_filing_intel
# - sec_compare_latest_to_previous
# - sec_semantic_search
# - earnings_call_intel
```

--------------------------------

### Starting the MCP Server

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Instructions on how to launch the Express server for the MCP application, including commands for production and development environments, and examples of making tool calls via the `/mcp` endpoint.

```APIDOC
## Starting the MCP Server

Launch the Express server with Context security middleware. The server accepts MCP tool calls via HTTP POST to `/mcp` endpoint with JSON-RPC 2.0 protocol.

### Method
Shell Command Execution

### Endpoint
`POST /mcp`

### Description
Start the SEC MCP server in either production or development mode. The server exposes an `/mcp` endpoint for receiving tool calls.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
JSON-RPC 2.0 request object for tool calls.

### Request Example
```bash
# Start server (production)
npm run start

# Start with auto-reload (development)
npm run dev
```

### Example Tool Call:
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'
```

### Response
#### Success Response (200)
Server starts successfully and listens on the configured port. Tool call responses are returned in JSON-RPC 2.0 format.

#### Response Example (for `tools/list` call)
```json
{
  "jsonrpc": "2.0",
  "result": [
    "sec_latest_filing_intel",
    "sec_compare_latest_to_previous",
    "sec_semantic_search",
    "earnings_call_intel"
  ],
  "id": 1
}
```

### Notes
- Server listens on configured port (default 3000).
- Available tools include `sec_latest_filing_intel`, `sec_compare_latest_to_previous`, `sec_semantic_search`, and `earnings_call_intel`.
```

--------------------------------

### Example Transcript JSON Structure

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

An example JSON structure for an earnings call transcript file. This format is expected by the `transcripts` ingestion script.

```json
{
  "ticker": "AAPL",
  "cik": "0000320193",
  "callDate": "2025-01-30",
  "fiscalYear": 2025,
  "fiscalQuarter": 1,
  "transcriptText": "..."
}
```

--------------------------------

### Database Schema Setup

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Instructions for initializing the PostgreSQL database with the `pgvector` extension and applying the initial migration script. Details key tables created for storing company, filing, chunk, XBRL, and intelligence report data.

```APIDOC
## Database Schema Setup

Initialize PostgreSQL with `pgvector` extension for semantic search. The schema supports companies, filings, sections, chunks with embeddings, XBRL facts, and precomputed intelligence reports.

### Method
SQL Command Execution

### Endpoint
`psql "$DATABASE_URL" -f db/migrations/001_init.sql`

### Description
Apply the initial database migration script to set up the necessary tables and indexes for the SEC MCP application.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
psql "$DATABASE_URL" -f db/migrations/001_init.sql
```

### Response
#### Success Response (200)
Database schema is initialized with required tables and extensions.

#### Response Example
```sql
-- Example output indicating successful migration (actual output may vary)
-- CREATE TABLE
-- CREATE INDEX
```

### Notes
Key tables created:
- `companies`: `cik` (PK), `ticker`, `name`
- `filings`: `cik`, `accession`, `form_type`, `filing_date`, `report_period`
- `filing_sections`: `filing_id`, `section_type`, `content_text`, `content_hash`
- `filing_chunks`: `filing_id`, `section_type`, `text`, `embedding` (vector 1536)
- `xbrl_facts`: `cik`, `tag`, `unit`, `end_date`, `value` (key financial metrics)
- `intel_reports`: `cik`, `filing_id`, `report_type`, `data_json` (precomputed)
- `earnings_calls`: `cik`, `call_date`, `transcript_text`
- `earnings_intel`: `call_id`, `data_json` (precomputed transcript analysis)

Vector search uses HNSW index for fast similarity queries:
```sql
CREATE INDEX filing_chunks_embedding_hnsw
  ON filing_chunks USING hnsw (embedding vector_cosine_ops);
```
```

--------------------------------

### Environment Variable Configuration (Bash)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Illustrates the necessary environment variables for configuring the SEC MCP project. This includes database connection details, SEC API user agent, server settings, embedding provider and model specifics, optional LLM and transcript integrations, and performance tuning parameters. A sample command to copy the example configuration file is also provided.

```bash
# Copy example config
cp .env.example .env

# Required configuration
DATABASE_URL=postgresql://user:pass@localhost:5432/sec_filings
SEC_USER_AGENT=YourName your.email@company.com

# Server settings
PORT=3000
MCP_HOST=0.0.0.0
MCP_ALLOWED_HOSTS=localhost,your-domain.com

# Embeddings (OpenAI or deterministic fallback)
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536

# Optional: LLM for summarization
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

# Optional: Earnings transcripts via FMP
TRANSCRIPT_PROVIDER=fmp
FMP_API_KEY=your_fmp_key

# Optional: Web search fallback via Tavily
TAVILY_API_KEY=your_tavily_key

# Performance tuning
CHUNK_MAX_WORDS=900
CHUNK_OVERLAP_WORDS=120
SEC_MIN_INTERVAL_MS=200
INGEST_FILING_CONCURRENCY=1
INGEST_SECTION_CONCURRENCY=3
PRECOMPUTE_CONCURRENCY=3
```

--------------------------------

### Database Schema Setup with pgvector (SQL)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Provides SQL commands to initialize a PostgreSQL database with the pgvector extension. It outlines the key tables created for storing company information, financial filings, their sections and chunks (including embeddings), XBRL facts, and precomputed intelligence reports. An HNSW index is created on the embedding column for efficient vector similarity searches.

```sql
-- Apply migration (requires PostgreSQL 14+ with pgvector)
psql "$DATABASE_URL" -f db/migrations/001_init.sql

-- Key tables created:
-- companies: cik (PK), ticker, name
-- filings: cik, accession, form_type, filing_date, report_period
-- filing_sections: filing_id, section_type, content_text, content_hash
-- filing_chunks: filing_id, section_type, text, embedding (vector 1536)
-- xbrl_facts: cik, tag, unit, end_date, value (key financial metrics)
-- intel_reports: cik, filing_id, report_type, data_json (precomputed)
-- earnings_calls: cik, call_date, transcript_text
-- earnings_intel: call_id, data_json (precomputed transcript analysis)

-- Vector search uses HNSW index for fast similarity queries
CREATE INDEX filing_chunks_embedding_hnsw
  ON filing_chunks USING hnsw (embedding vector_cosine_ops);
```

--------------------------------

### Get Earnings Call Intelligence with earnings_call_intel (Bash)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Retrieves precomputed intelligence for a company's earnings call. It requires the ticker, year, and quarter. The output includes an executive summary, tone analysis, guidance changes, and key quotes from management.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{\
    "jsonrpc": "2.0",\
    "method": "tools/call",\
    "params": {\
      "name": "earnings_call_intel",\
      "arguments": {\
        "ticker": "GOOGL",\
        "year": 2024,\
        "quarter": 3
      }
    },
    "id": 4
  }'
```

--------------------------------

### Apply Database Schema (psql)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Applies the initial database schema using psql. This command requires the DATABASE_URL environment variable to be set.

```bash
psql "$DATABASE_URL" -f db/migrations/001_init.sql
```

--------------------------------

### Database Migrations (SQL)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Contains the SQL scripts for setting up the Postgres database schema, including pgvector integration. Located in the `db/migrations/` directory.

```sql
-- db/migrations/ - Postgres schema + pgvector setup
```

--------------------------------

### Ingest SEC Filings (npm script)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Runs an offline pipeline to ingest SEC filings for a specified ticker. The `--ticker` argument is required.

```bash
npm run ingest -- --ticker AAPL
```

--------------------------------

### Precompute Intelligence (npm script)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Runs an offline pipeline to precompute intelligence data for a specified ticker. The `--ticker` argument is required.

```bash
npm run precompute -- --ticker AAPL
```

--------------------------------

### Server Implementation (JavaScript)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

The main Express MCP server implementation, including Context security middleware. Located at `src/server.js`.

```javascript
// src/server.js - Express MCP server + Context middleware
```

--------------------------------

### Ingest Transcripts (npm script)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Ingests earnings call transcripts from a specified file. The `--file` argument takes the path to the transcript file (JSON or text).

```bash
npm run transcripts -- --file ./transcripts/aapl_q1_2025.json
```

--------------------------------

### SEC Compare Latest to Previous Filing

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Compares the latest SEC filing with the previous one, providing metric deltas, narrative changes, and citations.

```APIDOC
## GET /sec_compare_latest_to_previous

### Description
Compares the latest SEC filing with the previous one, providing metric deltas, narrative changes, and citations.

### Method
GET

### Endpoint
/sec_compare_latest_to_previous

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol.
- **cik** (string) - Required - The Central Index Key for the company.
- **formType** (string) - Optional - The type of SEC form (e.g., '10-K', '10-Q').

### Response
#### Success Response (200)
- **metricDeltas** (object) - Changes in key financial metrics between filings.
- **narrativeChanges** (string) - Description of significant changes in the narrative sections.
- **citations** (array) - References to specific sections or data points.

#### Response Example
```json
{
  "metricDeltas": {
    "revenue": {
      "previous": 85000000000,
      "current": 89491000000,
      "delta": 4491000000
    },
    "grossProfit": {
      "previous": 38000000000,
      "current": 39870000000,
      "delta": 1870000000
    }
  },
  "narrativeChanges": "The risk factors section has been updated to include new information regarding supply chain vulnerabilities. Management's discussion and analysis highlights continued strong performance in the Services segment.",
  "citations": [
    "Item 1A. Risk Factors",
    "Item 7. Management's Discussion and Analysis of Financial Condition and Results of Operations"
  ]
}
```
```

--------------------------------

### MCP Tool Handlers (JavaScript)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Contains the schemas and handlers for the MCP tools. Located in the `src/mcp/` directory.

```javascript
// src/mcp/ - tool schemas and handlers
```

--------------------------------

### Configuration Environment Variables

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Lists essential environment variables required to configure the server, database connection, SEC API access, embedding provider, and optional LLM/transcript integrations.

```APIDOC
## Configuration Environment Variables

Configure the server, database, SEC API, embedding provider, and optional LLM/transcript integrations via environment variables.

### Method
Environment Variable Setting

### Endpoint
N/A (System-level configuration)

### Description
Set these environment variables before running the application to customize its behavior and integrations.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Copy example config
cp .env.example .env

# Required configuration
DATABASE_URL=postgresql://user:pass@localhost:5432/sec_filings
SEC_USER_AGENT=YourName your.email@company.com

# Server settings
PORT=3000
MCP_HOST=0.0.0.0
MCP_ALLOWED_HOSTS=localhost,your-domain.com

# Embeddings (OpenAI or deterministic fallback)
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536

# Optional: LLM for summarization
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

# Optional: Earnings transcripts via FMP
TRANSCRIPT_PROVIDER=fmp
FMP_API_KEY=your_fmp_key

# Optional: Web search fallback via Tavily
TAVILY_API_KEY=your_tavily_key

# Performance tuning
CHUNK_MAX_WORDS=900
CHUNK_OVERLAP_WORDS=120
SEC_MIN_INTERVAL_MS=200
INGEST_FILING_CONCURRENCY=1
INGEST_SECTION_CONCURRENCY=3
PRECOMPUTE_CONCURRENCY=3
```

### Response
#### Success Response (200)
Environment variables are set, allowing the application to run with the specified configuration.

#### Response Example
N/A (This is a configuration step, not an API response)

### Notes
Ensure `.env` file is correctly populated and accessible by the application.
```

--------------------------------

### Ingest SEC Filings with Form Types (bash)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Ingests SEC filings for a specific ticker, allowing filtering by form types. The `--forms` argument accepts a comma-separated list of form types.

```bash
npm run ingest -- --ticker AAPL --forms 10-Q,10-K
```

--------------------------------

### CLI: Ingest SEC Filings

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Command-line interface for ingesting SEC filings. Fetches filings, parses documents, chunks text, generates embeddings, and stores data.

```APIDOC
## CLI: Ingest SEC Filings

### Description
The ingest worker fetches SEC filings from EDGAR, parses HTML documents to extract sections (risk factors, MD&A, business description), chunks the text, generates embeddings, and stores everything in PostgreSQL. Also extracts XBRL financial facts for key metrics.

### Usage

#### Ingest a single company by ticker
```bash
npm run ingest -- --ticker AAPL
```

#### Ingest specific form types only
```bash
npm run ingest -- --ticker TSLA --forms 10-K,10-Q
```

#### Ingest by CIK (10-digit padded)
```bash
npm run ingest -- --cik 0000320193
```

#### Force re-ingestion (overwrite existing)
```bash
npm run ingest -- --ticker META --force
```

### Programmatic Usage

```javascript
import { ingestCompany } from './src/workers/ingest.js';

await ingestCompany({
  ticker: 'AAPL',
  forms: ['10-K', '10-Q'],
  force: false
});
```

### Pipeline Steps
1. Resolves CIK from SEC ticker map.
2. Fetches submissions JSON from data.sec.gov.
3. Downloads and parses each filing HTML document.
4. Extracts sections: risk_factors, mdna, business, financial_statements.
5. Chunks text (900 words max, 120 word overlap).
6. Generates embeddings via OpenAI or deterministic fallback.
7. Extracts XBRL facts: Revenues, NetIncomeLoss, Assets, etc.
8. Optionally fetches latest earnings transcript from FMP.
```

--------------------------------

### Perform Semantic Search with sec_semantic_search (Bash)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Executes a semantic search across company filings using vector similarity. It takes a ticker, a natural language query, an optional section type, and a limit for results. The response includes relevant chunks with metadata and similarity scores.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{\
    "jsonrpc": "2.0",\
    "method": "tools/call",\
    "params": {\
      "name": "sec_semantic_search",\
      "arguments": {\
        "ticker": "NVDA",\
        "query": "supply chain risks and manufacturing dependencies",\
        "sectionType": "risk_factors",\
        "limit": 5\
      }
    },
    "id": 3
  }'
```

--------------------------------

### Programmatic Usage

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Demonstrates how to programmatically precompute company and ticker data using the `precomputeCompany` and `precomputeForTicker` functions. This process generates key metrics, takeaways, risk analysis, signals, and metric deltas, storing them in the `intel_reports` table for efficient retrieval.

```APIDOC
## Programmatic Usage

This section details how to use the `precompute.js` module for generating intelligence reports.

### Method
Asynchronous Function Calls

### Description
Use `precomputeForTicker` to generate reports for a given stock ticker, or `precomputeCompany` with a company object for more specific control.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { precomputeCompany, precomputeForTicker } from './src/workers/precompute.js';

// By ticker
await precomputeForTicker('AMZN');

// By company object
const company = { cik: '0001018724', ticker: 'AMZN', name: 'Amazon.com Inc' };
await precomputeCompany(company);
```

### Response
#### Success Response (200)
Precomputation completes, and data is stored in the `intel_reports` table.

#### Response Example
```json
{
  "message": "Precomputation complete and data stored."
}
```

### Notes
Precompute generates:
- `latest_summary`: Key metrics, takeaways, risk analysis, signals
- `compare_previous`: Metric deltas, narrative changes, citations
Both are stored in the `intel_reports` table for O(1) retrieval.
```

--------------------------------

### Call sec_compare_latest_to_previous MCP Tool

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Shows how to invoke the 'sec_compare_latest_to_previous' MCP tool using an HTTP POST request. This tool compares a company's latest filing with its previous comparable filing, providing metric deltas and highlighting narrative changes in key sections like risk factors.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "sec_compare_latest_to_previous",
      "arguments": {
        "ticker": "MSFT",
        "formType": "10-Q"
      }
    },
    "id": 2
  }'
```

--------------------------------

### SEC Latest Filing Intelligence

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Retrieves metadata, key metrics, takeaways, risk summary, and signals for the latest SEC filing of a given ticker.

```APIDOC
## GET /sec_latest_filing_intel

### Description
Retrieves metadata, key metrics, takeaways, risk summary, and signals for the latest SEC filing of a given ticker.

### Method
GET

### Endpoint
/sec_latest_filing_intel

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol.
- **cik** (string) - Required - The Central Index Key for the company.
- **formType** (string) - Optional - The type of SEC form (e.g., '10-K', '10-Q').
- **includeSections** (string) - Optional - Comma-separated list of sections to include in the response.

### Response
#### Success Response (200)
- **filingMetadata** (object) - Metadata about the filing.
- **keyMetrics** (object) - Key financial metrics from the filing.
- **takeaways** (array) - Summary of important points from the filing.
- **riskSummary** (string) - Summary of risks mentioned in the filing.
- **signals** (array) - Identified signals from the filing.

#### Response Example
```json
{
  "filingMetadata": {
    "accessionNumber": "0001564590-23-028788",
    "filingDate": "2023-11-09",
    "reportDate": "2023-09-30",
    "formType": "10-Q"
  },
  "keyMetrics": {
    "revenue": 89491000000,
    "grossProfit": 39870000000
  },
  "takeaways": [
    "Strong revenue growth driven by iPhone sales.",
    "Increased investment in R&D."
  ],
  "riskSummary": "Risks include competition, supply chain disruptions, and macroeconomic factors.",
  "signals": [
    "Positive revenue trend",
    "Increased R&D spending"
  ]
}
```
```

--------------------------------

### SEC Semantic Search

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Performs a semantic search across SEC filings for a given ticker or CIK, returning top matching chunks with scores and snippets.

```APIDOC
## GET /sec_semantic_search

### Description
Performs a semantic search across SEC filings for a given ticker or CIK, returning top matching chunks with scores and snippets.

### Method
GET

### Endpoint
/sec_semantic_search

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol.
- **cik** (string) - Required - The Central Index Key for the company.
- **query** (string) - Required - The search query.
- **sectionType** (string) - Optional - The type of section to search within (e.g., '10-K', '10-Q', 'Risk Factors').
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- **results** (array) - An array of matching chunks, each containing a score and snippet.
  - **score** (float) - The relevance score of the chunk.
  - **snippet** (string) - The text snippet from the filing.

#### Response Example
```json
{
  "results": [
    {
      "score": 0.95,
      "snippet": "The company is exposed to risks related to global economic conditions, including inflation and potential recessions."
    },
    {
      "score": 0.88,
      "snippet": "Supply chain disruptions remain a significant risk, particularly for components sourced from overseas."
    }
  ]
}
```
```

--------------------------------

### Programmatic Data Precomputation (JavaScript)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Demonstrates how to precompute intelligence reports for a given ticker or company object using the precomputeForTicker and precomputeCompany functions. The precomputation process generates key metrics, risk analysis, signals, and comparative data, which are then stored in the intel_reports table for efficient retrieval.

```javascript
import { precomputeCompany, precomputeForTicker } from './src/workers/precompute.js';

// By ticker
await precomputeForTicker('AMZN');

// By company object
const company = { cik: '0001018724', ticker: 'AMZN', name: 'Amazon.com Inc' };
await precomputeCompany(company);
```

--------------------------------

### Earnings Call Intelligence

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Retrieves precomputed intelligence from earnings call transcripts for a given ticker, year, and quarter.

```APIDOC
## GET /earnings_call_intel

### Description
Retrieves precomputed intelligence from earnings call transcripts for a given ticker, year, and quarter.

### Method
GET

### Endpoint
/earnings_call_intel

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol.
- **cik** (string) - Required - The Central Index Key for the company.
- **year** (integer) - Required - The fiscal year of the earnings call.
- **quarter** (integer) - Required - The fiscal quarter of the earnings call.

### Response
#### Success Response (200)
- **transcriptIntel** (object) - Precomputed intelligence from the earnings call transcript.

#### Response Example
```json
{
  "transcriptIntel": {
    "keyTopics": [
      "Product Innovation",
      "Market Expansion",
      "Supply Chain Management"
    ],
    "analystQuestions": [
      "What are the key drivers for the upcoming product launch?",
      "How is the company addressing inflationary pressures?"
    ],
    "managementStatements": [
      "We are confident in our ability to execute our growth strategy.",
      "Our focus remains on delivering shareholder value."
    ],
    "sentiment": "Positive"
  }
}
```
```

--------------------------------

### Call sec_latest_filing_intel MCP Tool

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Demonstrates how to call the 'sec_latest_filing_intel' MCP tool via an HTTP POST request. This tool retrieves precomputed intelligence for a company's latest SEC filing, including financial metrics, risk analysis, and actionable signals. It requires the company ticker, form type, and an option to include specific sections.

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "sec_latest_filing_intel",
      "arguments": {
        "ticker": "AAPL",
        "formType": "10-K",
        "includeSections": false
      }
    },
    "id": 1
  }'
```

--------------------------------

### Ingest SEC Filings (CLI and Node.js)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Fetches, parses, and indexes SEC filings. It can ingest by ticker, CIK, or specific form types, with an option to force re-ingestion. Programmatically, it uses the `ingestCompany` function for a more controlled ingestion process.

```bash
# Ingest a single company by ticker
npm run ingest -- --ticker AAPL

# Ingest specific form types only
npm run ingest -- --ticker TSLA --forms 10-K,10-Q

# Ingest by CIK (10-digit padded)
npm run ingest -- --cik 0000320193

# Force re-ingestion (overwrite existing)
npm run ingest -- --ticker META --force
```

```javascript
import { ingestCompany } from './src/workers/ingest.js';

await ingestCompany({
  ticker: 'AAPL',
  forms: ['10-K', '10-Q'],
  force: false
});

// Pipeline output:
// 1. Resolves CIK from SEC ticker map
// 2. Fetches submissions JSON from data.sec.gov
// 3. Downloads and parses each filing HTML document
// 4. Extracts sections: risk_factors, mdna, business, financial_statements
// 5. Chunks text (900 words max, 120 word overlap)
// 6. Generates embeddings via OpenAI or deterministic fallback
// 7. Extracts XBRL facts: Revenues, NetIncomeLoss, Assets, etc.
// 8. Optionally fetches latest earnings transcript from FMP
```

--------------------------------

### Response Structure for sec_compare_latest_to_previous

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Details the JSON output format for the 'sec_compare_latest_to_previous' MCP tool. The response includes information on both the current and previous filings, a breakdown of metric deltas with percentage changes, and a list of narrative changes detected in sections such as risk factors.

```json
{
  "cik": "0000789019",
  "ticker": "MSFT",
  "current": {
    "filingId": "abc123-def456",
    "formType": "10-Q",
    "filingDate": "2024-10-30",
    "reportPeriod": "2024-09-30"
  },
  "previous": {
    "filingId": "xyz789-uvw012",
    "formType": "10-Q",
    "filingDate": "2023-10-31",
    "reportPeriod": "2023-09-30"
  },
  "metricDeltas": [
    {
      "tag": "Revenues",
      "label": "Total Revenue",
      "unit": "USD",
      "currentValue": 65585000000,
      "previousValue": 56517000000,
      "delta": 9068000000,
      "deltaPct": 0.1604
    },
    {
      "tag": "NetIncomeLoss",
      "label": "Net Income",
      "unit": "USD",
      "currentValue": 24667000000,
      "previousValue": 22291000000,
      "delta": 2376000000,
      "deltaPct": 0.1066
    }
  ],
  "narrativeChanges": [
    {
      "sectionType": "risk_factors",
      "newItems": [
        "AI-related investments may not generate expected returns..."
      ],
      "removedItems": [],
      "intensifiedItems": [
        "Competition from other technology companies continues to increase..."
      ],
      "citations": ["chunk-id-1", "chunk-id-2"]
    }
  ],
  "summary": "Total Revenue moved 16.0% vs prior period. Narrative changes detected in key sections."
}
```

--------------------------------

### Offline Pipeline Workers (JavaScript)

Source: https://github.com/harjaapdhillon16/sec_mcp/blob/main/README.md

Implements the offline pipelines for data ingestion, precomputation, and transcript processing. Located in the `src/workers/` directory.

```javascript
// src/workers/ - offline pipelines (ingest, precompute, transcripts)
```

--------------------------------

### MCP Tool: sec_compare_latest_to_previous

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Compares the latest SEC filing against the previous comparable filing (year-over-year for 10-K, quarter-over-quarter for 10-Q). It returns metric deltas with percentage changes and narrative changes detected in key sections.

```APIDOC
## POST /mcp

### Description
Compares the latest SEC filing against the previous comparable filing, providing metric deltas and narrative changes.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, should be "2.0".
- **method** (string) - Required - The method to call, should be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be "sec_compare_latest_to_previous".
  - **arguments** (object) - Required - Arguments for the sec_compare_latest_to_previous tool.
    - **ticker** (string) - Required - The stock ticker symbol of the company.
    - **formType** (string) - Required - The type of SEC filing (e.g., "10-K", "10-Q").
- **id** (integer) - Required - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "sec_compare_latest_to_previous",
    "arguments": {
      "ticker": "MSFT",
      "formType": "10-Q"
    }
  },
  "id": 2
}
```

### Response
#### Success Response (200)
- **cik** (string) - The CIK number of the company.
- **ticker** (string) - The stock ticker symbol.
- **current** (object) - Information about the current filing.
  - **filingId** (string) - Identifier for the current filing.
  - **formType** (string) - The type of the current filing.
  - **filingDate** (string) - The filing date of the current filing.
  - **reportPeriod** (string) - The report period of the current filing.
- **previous** (object) - Information about the previous comparable filing.
  - **filingId** (string) - Identifier for the previous filing.
  - **formType** (string) - The type of the previous filing.
  - **filingDate** (string) - The filing date of the previous filing.
  - **reportPeriod** (string) - The report period of the previous filing.
- **metricDeltas** (array) - An array of metric differences between the current and previous filings.
  - **tag** (string) - The XBRL tag for the metric.
  - **label** (string) - A human-readable label for the metric.
  - **unit** (string) - The unit of the metric (e.g., "USD").
  - **currentValue** (number) - The value of the metric in the current filing.
  - **previousValue** (number) - The value of the metric in the previous filing.
  - **delta** (number) - The absolute difference between current and previous values.
  - **deltaPct** (number) - The percentage change between current and previous values.
- **narrativeChanges** (array) - An array detailing narrative changes in key sections.
  - **sectionType** (string) - The type of section analyzed (e.g., "risk_factors").
  - **newItems** (array) - List of new disclosures or statements.
  - **removedItems** (array) - List of removed disclosures or statements.
  - **intensifiedItems** (array) - List of statements with intensified language.
  - **citations** (array) - References or citations related to the changes.
- **summary** (string) - A brief summary of the comparison results.

#### Response Example
```json
{
  "cik": "0000789019",
  "ticker": "MSFT",
  "current": {
    "filingId": "abc123-def456",
    "formType": "10-Q",
    "filingDate": "2024-10-30",
    "reportPeriod": "2024-09-30"
  },
  "previous": {
    "filingId": "xyz789-uvw012",
    "formType": "10-Q",
    "filingDate": "2023-10-31",
    "reportPeriod": "2023-09-30"
  },
  "metricDeltas": [
    {
      "tag": "Revenues",
      "label": "Total Revenue",
      "unit": "USD",
      "currentValue": 65585000000,
      "previousValue": 56517000000,
      "delta": 9068000000,
      "deltaPct": 0.1604
    },
    {
      "tag": "NetIncomeLoss",
      "label": "Net Income",
      "unit": "USD",
      "currentValue": 24667000000,
      "previousValue": 22291000000,
      "delta": 2376000000,
      "deltaPct": 0.1066
    }
  ],
  "narrativeChanges": [
    {
      "sectionType": "risk_factors",
      "newItems": [
        "AI-related investments may not generate expected returns..."
      ],
      "removedItems": [],
      "intensifiedItems": [
        "Competition from other technology companies continues to increase..."
      ],
      "citations": ["chunk-id-1", "chunk-id-2"]
    }
  ],
  "summary": "Total Revenue moved 16.0% vs prior period. Narrative changes detected in key sections."
}
```
```

--------------------------------

### CLI: Precompute Intelligence Reports

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Command-line interface for precomputing intelligence reports. Generates summaries, comparisons, deltas, and narrative change detection for fast MCP tool responses.

```APIDOC
## CLI: Precompute Intelligence Reports

### Description
The precompute worker generates intelligence reports that are cached for fast MCP tool responses. Computes latest filing summaries, period-over-period comparisons, metric deltas, and narrative change detection.

### Usage

#### Precompute for a single company
```bash
npm run precompute -- --ticker AMZN
```

#### Precompute by CIK
```bash
npm run precompute -- --cik 0001018724
```

#### Precompute all ingested companies
```bash
npm run precompute -- --all
```
```

--------------------------------

### Embedding Generation (JavaScript)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Explains the embedding generation capabilities, supporting OpenAI for production and a deterministic SHA-256 hash-based fallback for development. It demonstrates single and batch embedding generation using `embedText` and `embedTexts` functions, respectively. The module handles token limits, context errors, and automatic text trimming.

```javascript
import { embedText, embedTexts } from './src/lib/embeddings.js';

// Single text embedding
const embedding = await embedText('What are the main risk factors?');
// Returns: Float64Array[1536] with values in [-1, 1]

// Batch embeddings (auto-batched by token limit)
const texts = [
  'Revenue increased 15% year over year.',
  'Operating expenses grew due to increased R&D investment.',
  'Management expects continued growth in cloud services.'
];
const embeddings = await embedTexts(texts);
// Returns: Array of Float64Array[1536]

// Fallback mode (no OPENAI_API_KEY)
// Uses SHA-256 hash-based deterministic pseudo-embeddings
// Suitable for development/testing, not semantic similarity
```

--------------------------------

### Response Structure for sec_latest_filing_intel

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Illustrates the expected JSON response structure when using the 'sec_latest_filing_intel' MCP tool. The response contains details about the filing, key financial metrics, extracted takeaways, a summary of risks with sentiment scoring, and derived signals.

```json
{
  "cik": "0000320193",
  "ticker": "AAPL",
  "formType": "10-K",
  "filingDate": "2024-11-01",
  "reportPeriod": "2024-09-28",
  "primaryDocUrl": "https://www.sec.gov/Archives/edgar/data/320193/",
  "keyMetrics": [
    {
      "tag": "Revenues",
      "label": "Total Revenue",
      "value": 391035000000,
      "unit": "USD",
      "periodEnd": "2024-09-28",
      "fy": 2024,
      "fp": "FY"
    }
  ],
  "takeaways": [
    "Total Revenue changed -2.8% versus prior period.",
    "Risk factors section is ~12,450 words."
  ],
  "riskSummary": {
    "summary": "Risk factors emphasize global economic conditions...",
    "highlights": [
      "The Company's business can be negatively affected by...",
      "Political events and trade policies could disrupt..."
    ],
    "sentimentScore": -0.15
  },
  "signals": [
    "Watch Total Revenue movement (-2.8%).",
    "Risk tone skewed negative vs. baseline."
  ],
  "sections": []
}
```

--------------------------------

### Precompute Intelligence Reports (CLI)

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Generates cached intelligence reports for fast MCP tool responses. This worker computes summaries, comparisons, metric deltas, and narrative changes for companies. It can be run for a single company by ticker or CIK, or for all ingested companies.

```bash
# Precompute for a single company
npm run precompute -- --ticker AMZN

# Precompute by CIK
npm run precompute -- --cik 0001018724

# Precompute all ingested companies
npm run precompute -- --all
```

--------------------------------

### MCP Tool: sec_latest_filing_intel

Source: https://context7.com/harjaapdhillon16/sec_mcp/llms.txt

Retrieves precomputed intelligence for a company's most recent SEC filing (10-K, 10-Q, or 8-K). It includes key financial metrics, risk factor analysis with sentiment scoring, and actionable signals based on period-over-period changes.

```APIDOC
## POST /mcp

### Description
Fetches precomputed intelligence for a company's latest SEC filing (10-K, 10-Q, or 8-K), including financial metrics, risk analysis, and signals.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, should be "2.0".
- **method** (string) - Required - The method to call, should be "tools/call".
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be "sec_latest_filing_intel".
  - **arguments** (object) - Required - Arguments for the sec_latest_filing_intel tool.
    - **ticker** (string) - Required - The stock ticker symbol of the company.
    - **formType** (string) - Required - The type of SEC filing (e.g., "10-K", "10-Q", "8-K").
    - **includeSections** (boolean) - Optional - Whether to include detailed section content.
- **id** (integer) - Required - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "sec_latest_filing_intel",
    "arguments": {
      "ticker": "AAPL",
      "formType": "10-K",
      "includeSections": false
    }
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **cik** (string) - The CIK number of the company.
- **ticker** (string) - The stock ticker symbol.
- **formType** (string) - The type of SEC filing.
- **filingDate** (string) - The date the filing was made.
- **reportPeriod** (string) - The period the report covers.
- **primaryDocUrl** (string) - URL to the primary document of the filing.
- **keyMetrics** (array) - An array of key financial metrics.
  - **tag** (string) - The XBRL tag for the metric.
  - **label** (string) - A human-readable label for the metric.
  - **value** (number) - The value of the metric.
  - **unit** (string) - The unit of the metric (e.g., "USD").
  - **periodEnd** (string) - The end date of the period for the metric.
  - **fy** (integer) - The fiscal year for the metric.
  - **fp** (string) - The fiscal period for the metric.
- **takeaways** (array) - A list of key takeaways from the filing.
- **riskSummary** (object) - A summary of the risk factors.
  - **summary** (string) - A brief summary of the risks.
  - **highlights** (array) - Key highlights from the risk factors section.
  - **sentimentScore** (number) - A sentiment score for the risk factors.
- **signals** (array) - Actionable signals derived from the filing.
- **sections** (array) - Detailed sections of the filing (if `includeSections` was true).

#### Response Example
```json
{
  "cik": "0000320193",
  "ticker": "AAPL",
  "formType": "10-K",
  "filingDate": "2024-11-01",
  "reportPeriod": "2024-09-28",
  "primaryDocUrl": "https://www.sec.gov/Archives/edgar/data/320193/",
  "keyMetrics": [
    {
      "tag": "Revenues",
      "label": "Total Revenue",
      "value": 391035000000,
      "unit": "USD",
      "periodEnd": "2024-09-28",
      "fy": 2024,
      "fp": "FY"
    }
  ],
  "takeaways": [
    "Total Revenue changed -2.8% versus prior period.",
    "Risk factors section is ~12,450 words."
  ],
  "riskSummary": {
    "summary": "Risk factors emphasize global economic conditions...",
    "highlights": [
      "The Company's business can be negatively affected by...",
      "Political events and trade policies could disrupt..."
    ],
    "sentimentScore": -0.15
  },
  "signals": [
    "Watch Total Revenue movement (-2.8%).",
    "Risk tone skewed negative vs. baseline."
  ],
  "sections": []
}
```
```