# YC Data MCP

A read-only MCP server for querying a locally collected Y Combinator dataset without visiting the YC website.

## Current scope

- Uses only `YC Startup Directory Full Export.xlsx`
- Does not crawl or refresh YC data
- Preserves the source workbook unchanged
- Builds a typed SQLite database with normalized relations and full-text search
- Returns the snapshot observation time with every result
- Supports companies, founders, jobs, news, launches, company-level aggregation, and Founder Intelligence research

The bundled snapshot was observed at `2026-09-01T11:25:58.533589Z`.

## Architecture

```text
XLSX snapshot
    ↓
Raw records + import metadata
    ↓
Typed core entities and relations
    ├─→ Versioned derived source projections and provenance
    └─→ Summary view + FTS5 search indexes
            ↓
       Read-only repository
            ↓
       Deterministic Founder Intelligence
            ↓
       15 read-only MCP tools over stdio
```

See [docs/data-contract.md](docs/data-contract.md) for identity, transformation, quality, and freshness rules.

The current runtime is the deterministic data engine. A separate lifecycle-wide Founder Decision Agent is proposed, but not implemented, in [docs/founder-decision-agent-implementation-plan.md](docs/founder-decision-agent-implementation-plan.md).

## Requirements

- Python 3.11+
- `openpyxl` 3.1+ is installed with the package and used only when rebuilding the database
- SQLite with FTS5 support

The running MCP server itself uses only the Python standard library.

## Build the database

From the project root:

```bash
python3 scripts/build_database.py \
  --input "YC Startup Directory Full Export.xlsx" \
  --output data/yc.sqlite \
  --report data/build-report.json
```

The build is atomic: a failed build does not replace the last valid database.

## Run the MCP server

```bash
python3 scripts/run_server.py --database data/yc.sqlite
```

The server uses newline-delimited JSON-RPC over stdio and writes no logs to stdout.

## MCP client configuration

Use absolute paths in a desktop MCP client configuration:

```json
{
  "mcpServers": {
    "yc-data": {
      "command": "python3",
      "args": [
        "/absolute/path/to/yc-founder-intelligence/scripts/run_server.py",
        "--database",
        "/absolute/path/to/yc-founder-intelligence/data/yc.sqlite"
      ]
    }
  }
}
```

## Tools

| Tool | Purpose |
|---|---|
| `yc_dataset_info` | Snapshot time, entity counts, and quality counts |
| `yc_schema` | Supported entities, filters, sorts, and caveats |
| `yc_search` | Cross-entity full-text search |
| `yc_search_companies` | Structured company search and filters |
| `yc_get_company` | Company profile with optional relations |
| `yc_search_people` | Founder and company relationship search |
| `yc_search_jobs` | Job, skill, visa, location, salary, and age filters |
| `yc_search_news` | Deduplicated article search |
| `yc_search_launches` | Launch title, tagline, body, and date search |
| `yc_aggregate_companies` | Counts by batch, status, stage, country, remote policy, or hiring state |
| `yc_analyze_market` | Snapshot-bounded cohort, hiring, source-taxonomy, representative, and observed-outlier market evidence |
| `yc_find_competitors` | Evidence-backed related-company candidates for a supplied concept |
| `yc_compare_cohorts` | Compare 2–4 requested cohorts with baseline deltas and overlap disclosure |
| `yc_validate_startup_idea` | Snapshot-bounded startup-idea evidence scorecard, not a build recommendation |
| `yc_find_startup_opportunities` | Bounded opportunity hypotheses from approved structured signals, never proof of whitespace |

Use the existing search and detail tools for atomic evidence lookup. Use `yc_analyze_market` for structured market-evidence requests; unsupported semantic axes are reported rather than inferred. Use `yc_find_competitors` for similar-company or competitor requests. Use `yc_compare_cohorts` first for any natural-language request to compare two or more groups, batches, segments, or concepts, such as “Compare AI accounting companies in S25 and W26”; construct its cohort definitions with labels, concepts, and filters such as `batch_codes` rather than fetching each profile separately. Use `yc_find_startup_opportunities` for structured opportunity discovery. It supports only `category_acceleration`, `small_team_hiring_signal`, and `batch_share_growth`; every card is a hypothesis with support, counterevidence, evidence strength, limits, and validation questions. Use `yc_validate_startup_idea` for should-I-build or market-entry questions. Intelligence results are deterministic, snapshot-bounded evidence: they do not claim definitive competitors, success probabilities, market sizes, causal explanations, historical survival rates, or proof of market whitespace.

Search tools default to compact summaries, cap result sizes, validate all declared input types and limits, and support pagination. Full launch bodies require `limit: 1`. `yc_get_company` returns disambiguation candidates when a name is not unique.

## Examples

### Companies tagged Artificial Intelligence in the US with listed jobs

```json
{
  "tags": ["Artificial Intelligence"],
  "country_codes": ["US"],
  "has_listed_jobs": true,
  "limit": 10
}
```

### Remote backend roles with visa sponsorship

```json
{
  "query": "backend Python",
  "remote_only": true,
  "visa_policies": ["sponsorship_available"],
  "limit": 10
}
```

### Resolve a duplicate company name

```json
{
  "identifier": "Atlas"
}
```

This returns multiple candidates with IDs, batches, industries, and headlines instead of silently choosing one.

### Validate an AI accounting idea with local YC evidence

```json
{
  "concept": {
    "description": "AI accounting for small businesses",
    "search_terms": ["AI accounting", "accounting automation"],
    "problem_terms": ["accounting"],
    "customer_terms": ["small business"],
    "solution_terms": ["AI", "automation"],
    "industry_terms": ["fintech"]
  },
  "competitor_limit": 10
}
```

The response reports related-company candidates, batch momentum, current-status mix, hiring, launch activity, and lexical differentiation overlap. It does not recommend whether to build.

### Find structured opportunity hypotheses

```json
{
  "concept": {
    "description": "AI accounting for small businesses",
    "search_terms": ["AI accounting", "accounting automation"],
    "problem_terms": ["accounting"],
    "customer_terms": ["small business"],
    "solution_terms": ["AI", "automation"],
    "industry_terms": ["fintech"]
  },
  "strategies": ["batch_share_growth", "small_team_hiring_signal"],
  "recent_batch_count": 4,
  "baseline_batch_count": 4,
  "evidence_limit": 5
}
```

The response returns opportunity hypotheses only. Each has supporting evidence, counterevidence, bounded evidence strength, limitations, and next validation questions. It does not claim market growth, whitespace, or customer demand.

## Verification

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

The test suite covers normalization, structured filters, ambiguous names, truncated launch recovery, current modern MCP discovery, legacy initialization, tool calls, and required request metadata.

The last build report is in `data/build-report.json`.

## Protocol scope

The dependency-free stdio adapter supports MCP `2026-07-28` discovery and per-request metadata as well as legacy initialization for `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05`. It exposes read-only tools only. HTTP transport, authorization, prompts, resources, subscriptions, and data updates are intentionally out of scope for this MVP.

Before public package distribution, replacing the small protocol adapter with the official MCP Python SDK is recommended so future protocol revisions are inherited automatically.