v0.3.0

Two strands: giving an operator control over what the server sees and what it
may do, and a documentation pass aimed at readers who have never seen the
project.

Configuration

• Per-root .project-lens.json contributes exclude patterns for that root only,
  unioned with the global exclude. Never applies to a sibling root.
• exclude is the only key that file may set. It lives inside a scanned tree,
  so roots and allow_writes are ignored there by design: a cloned repository
  must not be able to widen the scan or enable writes. Malformed fails startup.
• allow_writes option with PROJECT_LENS_ALLOW_WRITES override. write_file and
  scaffold_project are not registered unless set, so a client that connects
  without them cannot call them.
• Stricter schema validation in loadConfig for exclude and allowWrites.

Benchmarks

• Scenarios labelled stable vs unstable, so non-reproducing results are marked
  rather than published beside ones that reproduce.
• Token cost separates default-session from write-enabled schema sets, and
  reports framing overhead and schema break-even directly.
• search gains a scope: "all" scenario; redundant percentiles dropped.

Tests

• 100% coverage across affected modules; new withFakeRg helper for ripgrep
  failure paths.
• Integration tests assert write-tool absence from the tool list, not just
  call refusal. Different guarantees, and only the former is what the security
  model claims.

Documentation

• README rewritten for a cold reader: what it is and why, reference material
  folded into collapsible sections, install routes and client registration
  recipes for Claude Code, Codex CLI, Gemini CLI and generic JSON clients.
• New CONTRIBUTING.md: setup, layout, design invariants, testing and
  benchmarking guidance, commit conventions, patch submission.

v0.2.0

Driven by two field reports from real work-PC usage: bulk metadata cost about
19x the tokens of the equivalent bash line, and SVN working copies were
invisible to the registry. A third report claim was checked and found false —
vcs data was never cached, only a misleading scanned_at field suggested it was.

Coverage

• Discovery indexes .svn working copies alongside .git; ProjectNode carries
  vcs_type: 'git' | 'svn'. The svn binary is never invoked, so remote, branch
  and is_clean stay null for those projects rather than being guessed.
• New tool list_files(project, glob?) over rg --files, respecting
  .gitignore, filtering secret-pattern files, capped at 500 with a truncated
  flag. Eleven tools total.
• read_file takes optional offset and limit for line-based paging.
• search takes limit (default 50, max 500) and reports truncated. Previously
  it capped silently at 100.
• scanned_at dropped from project_info and from ProjectNode; the tool
  description now states that vcs state is queried live on every call.

Token economy

• All structured responses are compact JSON. Pretty-printing cost 20-40% on
  every reply.
• list_projects takes include: ['branch','is_clean','stack'], so one call
  answers a whole-group metadata sweep instead of N project_info calls.
• list_projects returns a {fields, rows} matrix: rows are positional against
  fields, so keys are paid once rather than once per project. Same shape with
  and without include. This is a breaking change for any consumer that read
  payload.projects[i].name.

Benchmark

A token benchmark drives the real server over stdio and compares every tool
against an information-equivalent bash command, counting through Anthropic's
count_tokens against a pinned model. Without credentials it counts UTF-8
bytes and labels itself DEGRADED rather than silently substituting a proxy.

Measured on claude-opus-5 over 42 projects in 16 groups, mcp vs bash:
map_workspace 0.51, list_groups 0.58, list_files 0.61, project_info 0.68,
read_file 1.01-1.03, find_project 1.42, list_projects sweep 1.70,
write_file 1.74, list_projects 1.77, search 2.15. Schema cost is 1886 tokens
once per session, repaid by roughly three map_workspace calls.

The bulk sweep is 1355 tokens against 15184 for 42 project_info calls, 11.2x
smaller, past the 10x design target. The matrix took that figure from 6.6x.

The list_projects rows stay above parity by design: their bash baselines
print strictly less than the tool returns, so near-parity is the ceiling.

Latency is unchanged and well inside budget: cold scan 87 ms, registry tools
under 1 ms, project_info 5.6 ms, search 6.7 ms. 109 tests, 100% statements,
branches, functions and lines.

Requires Node.js >= 22, git and ripgrep on PATH. Three runtime dependencies.
The README now documents three install routes — an npm pack tarball needing no
registry, credentials or CA trust; clone and build; and a private registry —
plus how to register the server with clients other than Claude Code.

v0.1.0

Gives an MCP client a registry of the local project setup: group folders and git
projects discovered under configured roots, with scoped read/search/write
operations that cannot escape a project root.

Tools (10, stdio, MCP revision 2026-07-28 via @modelcontextprotocol/server 2.0.0):
map_workspace, list_groups, list_projects, find_project, project_info,
search, read_file, write_file, scaffold_project, refresh_registry

Behaviour

• Discovery: a directory containing .git is a project; the folders between a
  root and the project form its group path, at arbitrary depth.
• Freshness: full scan at startup, explicit refresh_registry, plus mtime
  revalidation of root and group dirs piggybacked on registry calls. No
  filesystem watcher, no disk cache.
• Configuration: PROJECT_LENS_PATH or a positional root argument; optional
  config file only for exclude globs and multiple roots. A malformed config
  fails startup rather than running with a silently widened scope.

Security

• Path traversal and symlink escapes rejected on every file operation.
• Secret-pattern files (.env*, .pem, id_rsa, credentials) never appear in
  key_files, listings or search results.
• Git remote userinfo (user:token@) stripped before it is returned.
• scaffold_project is user-initiated only, names allowlisted, no network; all
  subprocesses run through execFile argument arrays, never a shell.

Measured (personal PC, 42 projects / 16 groups): cold scan ~90 ms against a
500 ms budget, registry tools < 1 ms against 15-20 ms, project_info ~5 ms
against 100 ms, search ~7 ms against 80 ms.

Requires Node.js >= 22, git and ripgrep on PATH. Three runtime dependencies.
Published as @mpujado/project-lens to the private Gitea npm registry.