# VertiGIS Studio Web docs compiler and MCP server

Reference implementation for turning the VertiGIS Studio Developer Center's Web documentation into lean, provenance-preserving Markdown and exposing it through three MCP tools.

The design rationale and complete transformation contract are in [SPECIFICATION.md](SPECIFICATION.md).

## What it builds

- Normalized guides and tutorials from `docs/web/*.mdx`
- Commands, operations, events, config models, and argument types from the four runtime schemas
- `manifest.json` with stable IDs, paths, symbols, aliases, headings, source URLs, and snapshot hashes
- Heading-sized `chunks.json` for retrieval
- A short `index.md` agent map

The compiler is deterministic. It does not summarize or rewrite source prose with an LLM.

## Quick start

Requirements: Node.js 20+ and Git.

```bash
npm install
npm run build
npm run compile-docs
npm test
npm run serve
```

The first compile clones `vertigis/studio-dev-center` into `.work/`, downloads the current schemas, and writes `corpus/`. To compile an already checked-out repository:

```bash
VERTIGIS_SOURCE_DIR=/absolute/path/to/studio-dev-center npm run compile-docs
```

Optional environment variables:

| Variable              | Default                   | Purpose                       |
| --------------------- | ------------------------- | ----------------------------- |
| `VERTIGIS_SOURCE_DIR` | `.work/studio-dev-center` | Source repository checkout    |
| `VERTIGIS_WORK_DIR`   | `.work`                   | Download and schema workspace |
| `VERTIGIS_CORPUS_DIR` | `corpus`                  | Compiler output and MCP input |

## MCP client configuration

Build the project and point an MCP client at the stdio server:

```json
{
	"mcpServers": {
		"vertigis-studio-web-docs": {
			"command": "node",
			"args": ["/absolute/path/vertigis-docs-mcp/dist/src/server.js"],
			"env": {
				"VERTIGIS_CORPUS_DIR": "/absolute/path/vertigis-docs-mcp/corpus"
			}
		}
	}
}
```

Available tools:

| Tool                                            | Use                                                           |
| ----------------------------------------------- | ------------------------------------------------------------- |
| `get_symbol(name)`                              | Exact command, operation, event, config model, or type lookup |
| `search_docs(query, kind?, namespace?, limit?)` | Task/concept search with exact-identifier boosting            |
| `get_doc(id, heading?)`                         | Full document or one H2 section                               |

## Production hardening still recommended

- Parse MDX with an AST rather than regex for arbitrary future MDX components.
- Add link and anchor validation across the generated corpus.
- Add source-version pinning inputs instead of always taking the checked-out/current source.
- Add a golden regression set of 30–50 agent questions.
- Add an HTTP transport only if the deployment environment requires remote MCP access.

The current implementation is intentionally small and inspectable: it is a working baseline, not a claim that future MDX can never introduce a new transform rule.