# store — one MCP server, many collections

One [MCP](https://modelcontextprotocol.io) server that exposes **any number of personal "collections"** — todos, reading list, bookmarks, inventory, whatever you keep — through just **six generic tools**, driven by a YAML registry. Built for **small, local models**, where every extra tool you hand the model measurably degrades its tool-selection accuracy.

Instead of one MCP server (and four-plus tools) per list, `store` is **one server, six tools, N collections**. Add a new collection by writing a YAML file — no code.

> Background: this server is the subject of a write-up on running structured MCP tools against small local models. [PLACEHOLDER: article link]

## Why

A quantized local model has a limited attention budget, and every tool it's offered is a schema in its context. The more tools, the worse it selects — recent MCP studies put the knee around **10–15 tools** for smaller models. Mapping one tool per list doesn't scale.

`store` keeps the tool surface fixed at six no matter how many lists you keep, and a **declarative registry validates every write** — so a model can't quietly invent a `priority` field on Tuesday and an `urgency` field on Thursday and rot your data into a junk drawer.

## The six tools

| Tool | Does |
|---|---|
| `store_guide()` | Returns the usage guide — read first. |
| `store_describe(collection)` | A collection's exact fields, types, allowed values. |
| `store_add(collection, data)` | Add one record. |
| `store_update(collection, id, patch)` | Change fields on a record. |
| `store_remove(collection, id)` | Soft-delete (recoverable). |
| `store_query(collection, search, all, limit)` | Read records. |

## Quickstart

```bash
git clone https://github.com/<you>/store-mcp.git
cd store-mcp
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

python seed.py           # optional: a few demo rows so queries return something
python -m store.server   # run the MCP server over stdio
```

### Register it with a client

**Claude Code / any MCP client** — add to your MCP config:

```json
{
  "mcpServers": {
    "store": {
      "command": "/path/to/store-mcp/venv/bin/python",
      "args": ["-m", "store.server"],
      "cwd": "/path/to/store-mcp"
    }
  }
}
```

**LM Studio** — add the same entry to `~/.lmstudio/mcp.json`. LM Studio has no concept of "skills," so the skill reaches the model through the tool interface: `store_guide()` reads `store/skills/store/SKILL.md` and returns it as the tool's output — the model gets its routing instructions like any other tool result.

## Adding a collection

Drop a YAML file in `store/collections/`. It *is* the schema: a table is generated from it, and every write is validated against it.

```yaml
name: todos
description: Things I need to do
fields:
  title:  {type: string, required: true}
  due:    {type: date}
  notes:  {type: text}
  status: {type: enum, values: [open, done], default: open}
default_filter: "status = 'open'"
```

Field types: `string`, `text`, `int`, `number`, `bool`, `date`, `datetime`, `enum`. The columns `id`, `created_at`, `updated_at`, and `deleted_at` are added automatically.

## What ships

Seven example collections — keep, edit, or delete them: `todos`, `reading`, `watch`, `bookmarks`, `things` (physical inventory), plus a small cross-project work portfolio (`projects` + `initiatives`). They double as a tour of the pattern.

## Design notes

- **Registry as a write-time guardrail.** Unknown fields, wrong types, and bad enum values are rejected with a message that names the fix — a small model can't corrupt the schema, only retry to a valid record.
- **Soft delete.** `store_remove` sets `deleted_at`; every read filters it out. Nothing is truly destroyed.
- **Parameterized SQL.** Every model-supplied value is bound as a parameter; only registry-validated identifiers are ever interpolated into SQL.

## Tests

```bash
pip install pytest
python -m pytest store/tests -q
```

## License

MIT — see [LICENSE](LICENSE).