Skip to main content
Glama
README.md
# collegeplan

Planning how to pay for college starts with published numbers: what schools actually charge, what a 529 plan costs in fees, and which expenses the tax rules count as qualified. collegeplan is a small forwarding client for the hosted Launch529 open-data MCP service: the tool list is served from your own machine using the captured definitions, and each call is sent upstream, with the service's answer returned exactly as it arrived.

All seven of the service's captured tools are exposed. Nothing here takes personal data, and no tool opens an account, enrols anyone, or buys anything — the surface is read-only published data plus one projection compute and one rulebook check.

## The tools

- **`search_schools`** — Find colleges and universities by part of their name, in the US and at 529-eligible schools abroad. Returns each school's id, location and annual published costs. Requires `query`.
- **`get_school`** — One US school in detail, by the id from `search_schools`: current sticker price, average net price, net price by family income, cost history since 2005, graduation rate and median earnings. Requires `school_id`.
- **`estimate_college_cost`** — Project what college will cost and what to save. Requires `school_id` and `start_year`; optional `years`, `current_savings`, `monthly_contribution`, `annual_return_percent` and `housing` (`on_campus` or `off_campus`) tune the projection. Returns the projected cost per year and in total, and the monthly amount that would fully fund it.
- **`list_529_plans`** — State 529 savings plans ranked by popularity and ratings, with fees, ratings, state tax benefit and whether nonresidents can join. Every filter is optional: `state`, `open_to_nonresidents`, `max_fee_percent`, `top_rated`, `direct_sold_only` and `limit`. This tool has no required arguments.
- **`get_529_plan`** — One 529 plan in full: fees, minimums, investment options, ratings, state tax benefit, restrictions and features. Requires `plan`, a slug or part of the plan's name.
- **`compare_529_plans`** — Two to four 529 plans side by side on fees, ratings, tax benefit, minimums and who can join. Requires `plans`, an array of two to four slugs or names.
- **`check_expense`** — Whether a described expense is a qualified 529 expense, with the reason, based on IRS Publication 970. Requires `description`, for example `laptop` or `off-campus rent`.

## Install and run

As an MCP server via npm:

```bash
npx -y @reneturcios/collegeplan mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "collegeplan": {
      "command": "npx",
      "args": ["-y", "@reneturcios/collegeplan", "mcp"]
    }
  }
}
```

As a container:

```bash
docker run -i ghcr.io/cloudcorprecords/collegeplan
docker run --rm ghcr.io/cloudcorprecords/collegeplan search_schools '{"query":"san diego state"}'
```

## CLI

A single binary covers both the command line and the MCP server. Every tool is a subcommand whose one argument is a JSON string of that tool's inputs:

```bash
collegeplan search_schools '{"query":"san diego state"}'
collegeplan get_school '{"school_id":12345}'
collegeplan estimate_college_cost '{"school_id":12345,"start_year":2044}'
collegeplan list_529_plans '{}'
collegeplan get_529_plan '{"plan":"my529-ut"}'
collegeplan compare_529_plans '{"plans":["my529-ut","scholarshare-ca"]}'
collegeplan check_expense '{"description":"laptop"}'
collegeplan --version
```

Exit codes: `0` for a successful forwarded call, `1` when the result that comes back is an error, and `2` for usage mistakes like an unknown subcommand or a JSON argument that does not parse.

## Configuration

- `LAUNCH529_MCP_URL` — Replaces the upstream endpoint. Defaults to the pinned hosted endpoint, `https://launch529.com/api/public/mcp`. (This override variable is a reconstruction introduced by this rebuild.)

The Launch529 registry record lists no headers for its remote, so collegeplan never attaches an authentication header — every call goes upstream keyless.

When the upstream cannot answer — it returns a JSON-RPC error, answers with a non-2xx status, sends a body that cannot be read, or the request itself fails — the caller receives an error result whose text begins with `collegeplan error:`.

## How forwarding works

The first call of a process opens a session against the upstream: an `initialize` request (protocol version `2025-03-26`), a `notifications/initialized` notification, and then the `tools/call`. If the service issues an `Mcp-Session-Id` header during initialize, collegeplan repeats it on subsequent requests and keeps reusing that one session until the process ends. Replies are understood in both plain JSON and server-sent-events framing. Successful results are passed through untouched, `isError` flag and any extra fields included.

## Development

```bash
npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev     # run the CLI from source
```

The suite compares the served tool list against the captured surface tool for tool, walks the session handshake and its reuse, proves no `Authorization` header is sent under any environment, and confirms that arguments travel upstream unchanged and results return unchanged.

## License

MIT — see `LICENSE`. Copyright (c) 2026 Rene Turcios.