whetstone-mcp 0.1.0__tar.gz

whetstone_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Agent private working notes (CONTRIBUTING.md §2) — never committed
+.planning/
+
+# Agent memory — symlink to the harness's canonical per-project memory dir
+# (~/.claude/projects/<hash>/memory). Kept visible in-tree but never committed.
+/memory
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local model / embedding caches
+.cache/
+*.onnx
+
+# M3 showcase harness: the live, per-skill Whetstone store the harness seeds while generating
+# artifacts is throwaway (each store is its own nested git repo). The committed proof lives in
+# harness/out/, not here. Secrets for the generation runner also stay local.
+harness/.store/
+harness/.env
+
+# M3 Quarto site: rendered output + caches are built by CI (slice 9), not committed. The .qmd
+# sources under docs/ ARE committed.
+docs/_site/
+docs/.quarto/
+.quarto/
+
+# great-docs build directory (ephemeral). The great-docs.yml config IS committed; the generated
+# great-docs/ tree (Quarto sources + _site) is rebuilt by `great-docs build` and never committed.
+great-docs/
+
+# OS / editor
+.DS_Store

whetstone_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hrudith Lakshminarasimman
+
+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.

whetstone_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: whetstone-mcp
+Version: 0.1.0
+Summary: A local MCP server that lets any skill learn from use.
+Project-URL: Homepage, https://github.com/HrudithL/whetstone
+Project-URL: Repository, https://github.com/HrudithL/whetstone
+Project-URL: Documentation, https://github.com/HrudithL/whetstone
+Author-email: Hrudith Lakshminarasimman <hrudith.lakshminarasimman@posit.co>
+Maintainer-email: Hrudith Lakshminarasimman <hrudith.lakshminarasimman@posit.co>
+License: MIT
+License-File: LICENSE
+Keywords: agent,learning,mcp,memory,model-context-protocol,retrieval,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: mcp
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: great-docs>=0.15; extra == 'docs'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers; extra == 'embeddings'
+Provides-Extra: showcase
+Requires-Dist: claude-agent-sdk; extra == 'showcase'
+Requires-Dist: great-tables; extra == 'showcase'
+Requires-Dist: ipykernel; extra == 'showcase'
+Requires-Dist: jupyter; extra == 'showcase'
+Requires-Dist: matplotlib; extra == 'showcase'
+Requires-Dist: pandas; extra == 'showcase'
+Requires-Dist: python-pptx; extra == 'showcase'
+Requires-Dist: pyyaml; extra == 'showcase'
+Description-Content-Type: text/markdown
+
+# Whetstone
+
+A local [MCP](https://modelcontextprotocol.io) server that lets any skill learn from use.
+
+Whetstone attaches to an existing skill and maintains a git-tracked, per-skill store of what a
+user likes (`LEARNINGS`) and what the skill got wrong (`ISSUES`), so the skill can improve from
+ordinary use without a benchmark, dataset, or eval harness. See
+[`LEARNING_SKILLS_DESIGN.md`](https://github.com/HrudithL/whetstone/blob/main/LEARNING_SKILLS_DESIGN.md)
+for the full design.
+
+## Install
+
+Requires Python 3.11+. The base install is light and dependency-free at retrieval time: it uses a
+small, deterministic `hashing` embedding backend (no torch, no network).
+
+```sh
+pipx install whetstone-mcp     # installs the `whetstone` command on your PATH
+# or: pip install whetstone-mcp
+# or, run without installing: uvx whetstone-mcp
+```
+
+An install (pipx/pip) puts two equivalent console scripts on your PATH — `whetstone` (primary, used
+throughout this README) and `whetstone-mcp` (same entry point, so `pipx run whetstone-mcp` /
+`uvx whetstone-mcp` resolve without the short name).
+
+Register it with an MCP host (e.g. Claude Code) — point the host at whichever you used:
+
+```sh
+# if you installed it (pipx/pip): the command is already on PATH
+claude mcp add whetstone -- whetstone
+# no install — let uv fetch & run it on demand:
+claude mcp add whetstone -- uvx whetstone-mcp
+```
+
+For higher-quality embeddings, pull in the optional extra and set
+`embedding_backend = "sentence-transformers"` in config. Match the command to how it's installed:
+
+```sh
+pipx install "whetstone-mcp[embeddings]"                 # fresh install, with the extra
+pipx inject whetstone-mcp sentence-transformers          # add to an existing pipx install
+pip install "whetstone-mcp[embeddings]"                  # pip
+```
+
+### From source (contributors)
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+```sh
+.venv/bin/pip install -e '.[embeddings]'   # pulls in sentence-transformers
+```
+
+## Run
+
+Start the stdio MCP server:
+
+```sh
+whetstone            # PyPI install
+.venv/bin/whetstone   # from-source dev install
+```
+
+Register it with an MCP host (e.g. Claude Code) under the server id `whetstone`, pointing the
+command at the `whetstone` entry point above.
+
+## Tools
+
+The server exposes five MCP tools:
+
+- **`attach`** — register a skill so Whetstone tracks its learned layer (scaffolds the store).
+- **`recall`** — at the start of a task, retrieve the learnings (weighted preferences) and issues
+  (mandatory constraints) relevant to an *elaborated* intent.
+- **`capture`** — the moment you act on new user feedback, distill it into a scoped, deduped entry
+  (a preference → a learning; an always/never rule → an issue).
+- **`revise`** — reinforce / weaken / remove / promote / demote an entry `recall` already showed
+  (by id); confirmation-gated.
+- **`metrics`** — reporting only: the §11 KPIs per skill from each store's `events.jsonl`.
+
+### Maintenance
+
+Store compaction (retiring stale learnings, merging near-duplicate scopes) is deliberately **not**
+an MCP tool — it is out-of-band maintenance, run from the command line:
+
+```sh
+whetstone compact <skill>            # PyPI install
+.venv/bin/whetstone compact <skill>  # from-source dev install
+```
+
+## Storage & config
+
+Per-skill stores live under the XDG data dir, defaulting to
+`~/.local/share/whetstone/<skill-slug>/`, overridable via the `WHETSTONE_STORE_ROOT` environment
+variable or `store_root` in the config file. Configuration is read from
+`~/.config/whetstone/config.toml` (XDG config dir); every key also has a `WHETSTONE_*` env
+override. Each store is its own git repository:
+
+```
+<store-root>/<skill-slug>/
+  learnings/<scope-slug>.md   source of truth, grouped by scope
+  issues/<scope-slug>.md      source of truth, grouped by scope
+  next_ids.json               per-store monotonic id counters
+  index.sqlite                derived embedding cache (rebuildable, git-ignored)
+  events.jsonl                per-run telemetry for metrics (git-ignored)
+  .git/                       version history of the markdown
+```
+
+## Development
+
+```sh
+.venv/bin/ruff check .
+.venv/bin/pytest
+```

whetstone_mcp-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Whetstone
+
+A local [MCP](https://modelcontextprotocol.io) server that lets any skill learn from use.
+
+Whetstone attaches to an existing skill and maintains a git-tracked, per-skill store of what a
+user likes (`LEARNINGS`) and what the skill got wrong (`ISSUES`), so the skill can improve from
+ordinary use without a benchmark, dataset, or eval harness. See
+[`LEARNING_SKILLS_DESIGN.md`](https://github.com/HrudithL/whetstone/blob/main/LEARNING_SKILLS_DESIGN.md)
+for the full design.
+
+## Install
+
+Requires Python 3.11+. The base install is light and dependency-free at retrieval time: it uses a
+small, deterministic `hashing` embedding backend (no torch, no network).
+
+```sh
+pipx install whetstone-mcp     # installs the `whetstone` command on your PATH
+# or: pip install whetstone-mcp
+# or, run without installing: uvx whetstone-mcp
+```
+
+An install (pipx/pip) puts two equivalent console scripts on your PATH — `whetstone` (primary, used
+throughout this README) and `whetstone-mcp` (same entry point, so `pipx run whetstone-mcp` /
+`uvx whetstone-mcp` resolve without the short name).
+
+Register it with an MCP host (e.g. Claude Code) — point the host at whichever you used:
+
+```sh
+# if you installed it (pipx/pip): the command is already on PATH
+claude mcp add whetstone -- whetstone
+# no install — let uv fetch & run it on demand:
+claude mcp add whetstone -- uvx whetstone-mcp
+```
+
+For higher-quality embeddings, pull in the optional extra and set
+`embedding_backend = "sentence-transformers"` in config. Match the command to how it's installed:
+
+```sh
+pipx install "whetstone-mcp[embeddings]"                 # fresh install, with the extra
+pipx inject whetstone-mcp sentence-transformers          # add to an existing pipx install
+pip install "whetstone-mcp[embeddings]"                  # pip
+```
+
+### From source (contributors)
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+```sh
+.venv/bin/pip install -e '.[embeddings]'   # pulls in sentence-transformers
+```
+
+## Run
+
+Start the stdio MCP server:
+
+```sh
+whetstone            # PyPI install
+.venv/bin/whetstone   # from-source dev install
+```
+
+Register it with an MCP host (e.g. Claude Code) under the server id `whetstone`, pointing the
+command at the `whetstone` entry point above.
+
+## Tools
+
+The server exposes five MCP tools:
+
+- **`attach`** — register a skill so Whetstone tracks its learned layer (scaffolds the store).
+- **`recall`** — at the start of a task, retrieve the learnings (weighted preferences) and issues
+  (mandatory constraints) relevant to an *elaborated* intent.
+- **`capture`** — the moment you act on new user feedback, distill it into a scoped, deduped entry
+  (a preference → a learning; an always/never rule → an issue).
+- **`revise`** — reinforce / weaken / remove / promote / demote an entry `recall` already showed
+  (by id); confirmation-gated.
+- **`metrics`** — reporting only: the §11 KPIs per skill from each store's `events.jsonl`.
+
+### Maintenance
+
+Store compaction (retiring stale learnings, merging near-duplicate scopes) is deliberately **not**
+an MCP tool — it is out-of-band maintenance, run from the command line:
+
+```sh
+whetstone compact <skill>            # PyPI install
+.venv/bin/whetstone compact <skill>  # from-source dev install
+```
+
+## Storage & config
+
+Per-skill stores live under the XDG data dir, defaulting to
+`~/.local/share/whetstone/<skill-slug>/`, overridable via the `WHETSTONE_STORE_ROOT` environment
+variable or `store_root` in the config file. Configuration is read from
+`~/.config/whetstone/config.toml` (XDG config dir); every key also has a `WHETSTONE_*` env
+override. Each store is its own git repository:
+
+```
+<store-root>/<skill-slug>/
+  learnings/<scope-slug>.md   source of truth, grouped by scope
+  issues/<scope-slug>.md      source of truth, grouped by scope
+  next_ids.json               per-store monotonic id counters
+  index.sqlite                derived embedding cache (rebuildable, git-ignored)
+  events.jsonl                per-run telemetry for metrics (git-ignored)
+  .git/                       version history of the markdown
+```
+
+## Development
+
+```sh
+.venv/bin/ruff check .
+.venv/bin/pytest
+```

whetstone_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "whetstone-mcp"
+version = "0.1.0"
+description = "A local MCP server that lets any skill learn from use."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Hrudith Lakshminarasimman", email = "hrudith.lakshminarasimman@posit.co" },
+]
+maintainers = [
+    { name = "Hrudith Lakshminarasimman", email = "hrudith.lakshminarasimman@posit.co" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "skills",
+    "learning",
+    "memory",
+    "retrieval",
+    "agent",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp",
+]
+
+[project.urls]
+Homepage = "https://github.com/HrudithL/whetstone"
+Repository = "https://github.com/HrudithL/whetstone"
+Documentation = "https://github.com/HrudithL/whetstone"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+]
+# Heavy, optional. The default "hashing" embedding backend needs none of this; only the
+# "sentence-transformers" backend does. Install with: pip install "whetstone-mcp[embeddings]".
+embeddings = [
+    "sentence-transformers",
+]
+# Showcase harness only (M3). Never needed to run the MCP server; used by the internal, command-only
+# harness under `harness/` to generate the site's before/after artifacts and metrics. The harness
+# also requires the `embeddings` extra (it runs on the sentence-transformers backend) and the Claude
+# Code CLI on PATH (claude-agent-sdk drives it). Install with:
+#   pip install -e ".[showcase,embeddings]"
+showcase = [
+    "great-tables",
+    "pandas",
+    "claude-agent-sdk",
+    "matplotlib",
+    "pyyaml",
+    # The pptx showcase skill's generated deck.py builds a deck with python-pptx; the --agent runner
+    # runs that script in this venv, so the dep must be importable here.
+    "python-pptx",
+    # Quarto site render (jupyter engine): the docs/ pages execute Python to read out/ and render
+    # great-tables natively + matplotlib charts.
+    "jupyter",
+    "ipykernel",
+]
+# Docs site (spike/great-docs-site): great-docs auto-generates the /docs API+MCP reference site.
+# Needs Quarto on PATH too (installed separately, not a pip package). Install with:
+#   pip install -e ".[docs]"
+docs = [
+    "great-docs>=0.15",
+]
+
+[project.scripts]
+whetstone = "whetstone.server:main"
+# Alias so `uvx whetstone-mcp` / `pipx run whetstone-mcp` resolve without knowing the short name.
+# `whetstone` remains the primary command referenced in docs.
+whetstone-mcp = "whetstone.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/whetstone"]
+
+# Lean sdist: only what's needed to build + install the package, plus the files PyPI renders/needs
+# for licensing. Explicitly excludes harness/ (incl. harness/data/*.csv, ~920KB, and harness/out/),
+# docs/, site/, tests/, and the design *.md files — none of that is needed to run the MCP server.
+# Note: hatchling's sdist builder unconditionally force-includes the project's .gitignore as VCS
+# metadata (SdistBuilder.get_default_build_data(), no config knob to disable) — it will still show
+# up in the tarball listing alongside these; its contents are plain ignore globs, nothing sensitive.
+[tool.hatch.build.targets.sdist]
+# Patterns are anchored to the project root with a leading "/" — otherwise hatchling matches
+# README.md/LICENSE at any depth (gitignore-style), which pulls in harness/*/README.md too.
+include = [
+    "/src/whetstone",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+# Vendored third-party content (the great-tables Claude skill copied from the sibling gtskill repo)
+# is not ours to lint/format. `harness/out` is model-generated showcase output, committed verbatim so
+# the site can embed it and cold->warm diffs stay reviewable — an artifact, not source to lint.
+extend-exclude = ["harness/skill", "harness/out"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    # Backend-sensitive checks that need the real sentence-transformers model (the [embeddings]
+    # extra). Run as a separate CI job: `pytest -m embeddings`. The fast default job excludes them
+    # with `pytest -m "not embeddings"`, and they self-skip when the extra is not installed.
+    "embeddings: requires the sentence-transformers backend ([embeddings] extra)",
+]

whetstone_mcp-0.1.0/src/whetstone/__init__.py

@@ -0,0 +1,5 @@
+"""Whetstone: a local MCP server that lets any skill learn from use."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"