grill-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Danielsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# grill-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+grill-mcp gives any AI agent access to [Grill](https://grill.onbridger.com)'s record of what you know. The record holds every concept from your notes you have been tested on, your chance of recalling each one today, what you got wrong last time, and the misconceptions you keep showing. An agent connected to it can therefore pitch an explanation at your level, name the specific confusion behind a mistake, and test you on what is fading. Answers given to the agent count in Grill as well.
+
+## Setup
+
+In Obsidian, open Settings → Grill → Agents and copy the line for your agent. It has this form:
+
+```
+claude mcp add --scope user grill -- npx -y grill-mcp --vault "/path/to/your/vault"
+codex mcp add grill -- npx -y grill-mcp --vault "/path/to/your/vault"
+```
+
+Any other MCP client runs the same command, `npx -y grill-mcp --vault <path>`, over stdio. It requires Node.js 18 or later.
+
+Without `--vault`, grill-mcp uses the vault it is started in, including from one of the vault's subfolders, or the folder named by the `GRILL_VAULT` environment variable. `--dir <path>` keeps a record in a folder of its own, outside any vault.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `grill_overview` | Counts of tested, known and still-learning concepts, what is due now or fading this week, the weakest notes and active misconceptions. |
+| `grill_weak_spots` | Concepts missed last time, missed repeatedly, or likely forgotten, weakest first, optionally for one topic. |
+| `grill_what_they_know` | Everything the record holds on a topic, for pitching an explanation. |
+| `grill_questions` | Questions Grill already wrote for the concepts most worth testing, with expected answers for grading. |
+| `grill_record_answer` | Records one graded answer, which then moves that concept's schedule. |
+
+The server also tells the agent how to test: one question at a time, the expected answer kept back until you have answered, and every answer recorded.
+
+## Commands
+
+The same queries are available as plain commands, for an agent that has a shell but no MCP set up. Each prints JSON. The `grill-test` skill uses them.
+
+```
+npx -y grill-mcp overview
+npx -y grill-mcp weak-spots [topic]
+npx -y grill-mcp know <topic>
+npx -y grill-mcp questions [topic]
+npx -y grill-mcp record '{"note": "...", "question": "...", "answer": "...", "verdict": "partial"}'
+```
+
+## How answers reach Grill
+
+grill-mcp never writes to the record files themselves, since the plugin may hold them open. Each graded answer is instead written as one file in the `Inbox` folder inside your Grill folder. While Grill is open, it adds these answers to the record within a few seconds, writes a session note for each agent session, and removes the files. Each answer is counted once, including when the vault syncs to a second device.
+
+## Outside a vault
+
+Run in a folder that is not an Obsidian vault, for instance a code repository, grill-mcp keeps a record of its own in `.grill/` and updates it directly, one writer at a time. A readable log of each day's questions and answers is kept in `.grill/Sessions/`. A record file that cannot be read is reported as an error and never written over.
+
+## Privacy
+
+grill-mcp makes no network requests. It reads and writes files in your vault, or in `.grill/`, and nothing else. What the agent does with the record is subject to that agent's own terms.
+
+MIT licence.