# Codebase Structure

## Source (`src/`) — 28 TypeScript files (+ 2 ambient `.d.ts`)
### Core Server
- `mcp-server.ts` — QsvMcpServer class, main entry point, tool dispatch (`toolDispatchMap`)
- `index.ts` — library entry point (re-exports public API)
- `config.ts` — centralized config via `QSV_MCP_*` env vars
- `types.ts` — shared interfaces (QsvSkill, SkillParams, McpToolResult, etc.)
- `version.ts` — version resolution + package.json/manifest.json parity check

### Tool System
- `mcp-tools.ts` — barrel re-export of public symbols (back-compat surface for tests + consumers)
- `tool-definitions.ts` — MCP tool schema creation (createToolDefinition, createGenericToolDefinition)
- `tool-handlers.ts` — tool call processing (handleToolCall, handleGenericCommand)
- `tool-constants.ts` — pure constants (COMMON_COMMANDS, MAX_*, AUTO_INDEX_SIZE_MB, symbols)
- `command-guidance.ts` — COMMAND_GUIDANCE map with emoji-coded hints

### Execution
- `executor.ts` — SkillExecutor class: validates params, builds args, runs qsv
- `concurrency.ts` — slot-based concurrency control for parallel operations
- `spawn-utils.ts` — child process spawn utilities (kill grace period, stdout/stderr caps)

### Skill Loading
- `loader.ts` — SkillLoader: loads/indexes JSON skill definitions from `qsv/` dir
- `bm25-search.ts` — ToolSearchIndex: BM25 full-text search over tools

### Filesystem & Files
- `mcp-filesystem.ts` — FilesystemResourceProvider: file listing, metadata, conversion
- `file-operations.ts` — file path resolution, conversion args, output formatting
- `converted-file-manager.ts` — tracks Excel/ODS → CSV conversions (LIFO cache)
- `working-dir-manager.ts` — working dir state, elicitation, MCP roots sync (extracted from mcp-server.ts)

### Integrations
- `duckdb.ts` — DuckDB SQL query integration
- `parquet-bridge.ts` — Parquet format support
- `mcp-sampling.ts` — MCP sampling protocol support

### Utilities
- `utils.ts` — error handling, result helpers, version comparison
- `update-checker.ts` — checks for qsv updates
- `pipeline-manifest.ts` — pipeline/workflow manifest (reproducibility)
- `browse-directory.ts` — directory browsing UI
- `installer.ts` — installation helpers
- `ui/directory-picker-html.ts` — HTML UI for directory picker

### Ambient types
- `wink-bm25-text-search.d.ts`, `wink-nlp-utils.d.ts`

## Tests (`tests/`) — 26 `.test.ts` files + `test-helpers.ts` + `fixtures/`
Mirror source structure: `tests/<module>.test.ts`. Notable: `qsv-integration.test.ts`, `mcp-app.test.ts`, `deferred-loading.test.ts`, `elicitation.test.ts`, `tool-filtering.test.ts`, `tsv-output.test.ts`, `hook-scripts.test.ts`.

## Skills (`qsv/`) — 54 auto-generated JSON skill files
Named `qsv-<command>.json`, generated by `qsv --update-mcp-skills` from repo root. Plus `README.md`.

## Agents (`agents/`) — 3 markdown agent definitions
`data-analyst.md`, `data-wrangler.md`, `policy-analyst.md`

## Skills Workflows (`skills/`) — 15 skill directories
`bls-query`, `csv-query`, `csv-wrangling`, `data-clean`, `data-convert`, `data-describe`, `data-join`, `data-profile`, `data-quality`, `data-validate`, `data-viz`, `genai-disclaimer`, `infer-ontology`, `qsv-performance`, `reproducible-analysis`

## Scripts (`scripts/`) — 11 build / packaging / hook scripts
`clean-bundles.js`, `cowork-setup.cjs`, `install-mcp.js`, `log-session-end.cjs`, `log-turn-summary.cjs`, `log-user-prompt.cjs`, `log-web-results.cjs`, `package-mcpb.js`, `package-plugin.js`, `qsv-utils.cjs`, `run-tests.js`

## Other top-level
- `hooks/` — `hooks.json` for Claude Code hooks
- `docs/` — documentation files
- `.claude-plugin/plugin.json` — Cowork plugin manifest (name, version, author, keywords); no `.mcp.json` is referenced
- `manifest.json` — Claude Desktop extension/plugin manifest (version must match `package.json`)
- `qsv-data-wrangling-<version>.plugin` — packaged Cowork plugin
- `qsv-mcp-server-<version>.mcpb` — packaged MCP bundle
