# glasz-mcp

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that
fetches glasz-style spec files (the `product.md` / `tech.md` / `test-plan.md`
trio + the derived `specs/INDEX.md`) from GitHub repositories and hands them to
an LLM client, so the model can answer questions about features, stories, and AC
status without the user cloning the repo or pasting files.

It is intentionally a thin window onto the same source data that glasz the app
reads — no writes, no parsing on the server (the LLM interprets the trio,
guided by the server `instructions` block).

## Status — v1-core

This release implements the v1-core scope:

| Story | What |
|---|---|
| S1 | Install via `npx -y github:quintegro/glasz-mcp` (compiled `dist/` is committed) |
| S4 | `get_index` — fetch `specs/INDEX.md` |
| S5 | `get_feature` — fetch a feature's trio |
| S6 | `instructions` schema legend taught at `initialize` |

Deferred to v1.x: **S2** (OAuth device-flow `login` — currently a stub) and
**S3** (`list_repos` discovery — not registered).

## Install

Add this to your MCP client config (Claude Desktop / Claude Code / Cursor):

```json
{
  "command": "npx",
  "args": ["-y", "github:quintegro/glasz-mcp"],
  "env": { "GITHUB_REPO": "owner/name" }
}
```

`GITHUB_REPO` is optional — when set, tools default to it if `repo` is omitted.

### Authentication

Public repositories are readable without a token. For private repos, set
`GITHUB_TOKEN` in the client config `env`, or place a token at
`~/.glasz-mcp/auth.json` (mode `0600`):

```json
{ "access_token": "ghp_…", "token_type": "bearer", "scope": "repo", "login": "you", "created_at": "2026-06-19T00:00:00Z" }
```

The OAuth device-flow `login` command is deferred to v1.x.

## Tools

- **`get_index({ repo? })`** — returns the raw markdown of `specs/INDEX.md`.
- **`get_feature({ repo?, slug })`** — returns the trio for `specs/features/<slug>/`.

## Development

```bash
pnpm install        # also runs `prepare` → build
pnpm run build      # tsc → dist/
pnpm test           # unit + integration (vitest)
node bin/glasz-mcp.js   # start the server on stdio
```

`dist/` is committed to git (not `.gitignored`) because `npx` git-installs do
not run build scripts — the compiled output must exist on the default branch.