ouncemcp 1.0.0rc1__tar.gz

ouncemcp-1.0.0rc1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.env
+ouncemcp-report.*
+site/
+.hypothesis/

ouncemcp-1.0.0rc1/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to OunceMCP. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [semantic versioning](https://semver.org/) with the promises in [proposal 0029](https://github.com/subbusainath/ouncemcp/blob/main/docs/proposals/0029-api-freeze.md).
+
+## 1.0.0rc1 (15 November 2026)
+
+Release candidate for 1.0.0. Install it with `pip install --pre ouncemcp` or `pipx install "ouncemcp==1.0.0rc1"`. 1.0.0 follows the external security review; the API below will not change before it unless the review requires it.
+
+The first stable release. The public API is frozen: names listed as stable in proposal 0029 do not change in a breaking way before 2.0.
+
+### Stable
+
+- **Server and tools** (`ouncemcp`): `OunceServer` with typed tools, declared effects, resources, prompts and background jobs; `ToolContext`; budgets and per-tool overrides; response shaping with `Detail`, `Paginated` and signed `Cursor`s; automatic discovery; errors in eight categories; deadlines, retries and limits; stores, idempotent writes and approvals; handles and resumable jobs; tokenizers and cost reports.
+- **Security** (`ouncemcp.security`): verified identity, policies, partitioned caches, signed state, safe outbound fetches and token-passthrough guards.
+- **Clients** (`ouncemcp.client`): the `Broker` over many servers and `OunceOAuth`.
+- **Traces** (`ouncemcp.trace`): the tracer, its sinks and redaction.
+- **Testing** (`ouncemcp.testing`) and the **security suite** (`ouncemcp.eval`).
+- **Contracts outside Python:** error categories and codes, `_meta["ouncemcp"]` keys, the `handles.read` and `jobs.get` tools, command names, flags and exit codes, report `report_version`, and lint rule names.
+
+### Provisional
+
+May change in a minor release, with the change named here: `ouncemcp.eval.agent` (task suites and models), `ouncemcp.eval.bench`, `ouncemcp.ui` and `AnthropicCounter`.
+
+### Added
+
+- `AnthropicCounter` and `--tokenizer anthropic:MODEL`: token counts from Anthropic's counting API, through the official SDK (`pip install "ouncemcp[anthropic]"`). Provisional (spec BUD-6).
+
+### Deprecated
+
+- `ouncemcp.security.resolve_http_options` and `ouncemcp.security.partition_key` are internal. They still work but raise a `DeprecationWarning`, and will be removed in 1.1. `OunceServer.run` and `PartitionedCache` use them for you.
+
+### Changed
+
+- FastMCP is supported as a range, `>=4.1.6,<5`, instead of an exact pin. CI tests the lowest version (the lockfile) and the newest release in the range.
+
+### Supported versions
+
+- Python 3.11, 3.12 and 3.13.
+- FastMCP 4.1.6 and later 4.x releases.

ouncemcp-1.0.0rc1/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to OunceMCP
+
+OunceMCP is pre-alpha. The best contributions right now are feedback on the [specification](docs/spec.md) through issues.
+
+## Good first contributions
+
+These are designed to be small and self-contained:
+
+- New lint rules for tool definitions, each with a fixture that triggers it and a documentation page.
+- New benchmark servers or task suites with verifiable outcomes.
+- Documentation fixes.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run pytest
+uv run ruff check .
+```
+
+## Pull requests
+
+- Keep changes focused and include tests.
+- Changes to the public API or default behavior need a design proposal in `docs/proposals/`.
+- Any change that affects token usage should state its measured effect.
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Public API changes
+
+`tests/test_api_surface.py` records every exported name and public signature of `ouncemcp`, `ouncemcp.security`, `ouncemcp.client`, `ouncemcp.eval.agent`, `ouncemcp.testing` and `ouncemcp.ui` in `tests/api_snapshot.json`. A change to the public API fails it on purpose. If the change is intended, regenerate the snapshot with `OUNCEMCP_UPDATE_API_SNAPSHOT=1 uv run pytest tests/test_api_surface.py` and explain the change in the PR. After 1.0, removing or changing a public name needs a deprecation first.
+

ouncemcp-1.0.0rc1/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

ouncemcp-1.0.0rc1/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: ouncemcp
+Version: 1.0.0rc1
+Summary: Build MCP servers and clients that are fast, low-noise, and safe for agents by default.
+Project-URL: Homepage, https://subbusainath.github.io/ouncemcp/
+Project-URL: Documentation, https://subbusainath.github.io/ouncemcp/
+Project-URL: Repository, https://github.com/subbusainath/ouncemcp
+Project-URL: Changelog, https://github.com/subbusainath/ouncemcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/subbusainath/ouncemcp/issues
+Author: Subbusainath Rengasamy
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,fastmcp,llm,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<5,>=4.1.6
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: tiktoken==0.14.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic<3,>=2.3; extra == 'anthropic'
+Provides-Extra: client
+Provides-Extra: dev
+Requires-Dist: anthropic<3,>=2.3; extra == 'dev'
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.28; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material==9.8.1; extra == 'docs'
+Requires-Dist: mkdocs==1.6.1; extra == 'docs'
+Requires-Dist: mkdocstrings-python==2.0.11; extra == 'docs'
+Requires-Dist: mkdocstrings==1.0.8; extra == 'docs'
+Provides-Extra: eval
+Requires-Dist: pyyaml>=6; extra == 'eval'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.28; extra == 'otel'
+Provides-Extra: ui
+Description-Content-Type: text/markdown
+
+# OunceMCP
+
+**Every token counts.** OunceMCP is a framework for building Model Context Protocol (MCP) servers and clients that are fast, low-noise, and safe for agents by default. It builds on [FastMCP](https://gofastmcp.com) and the official MCP Python SDK, and targets the MCP `2026-07-28` specification.
+
+> **Status: pre-1.0 (M0 to M4 built).** The framework, safe writes, jobs, the client broker, the eval kit, the trace viewer and the benchmark work and are tested; the official MCP conformance suite passes in CI and the M4 performance gates are met ([M4 report](docs/m4-report.md)). The 1.0 API is frozen ([proposal 0029](docs/proposals/0029-api-freeze.md), [changelog](CHANGELOG.md)); 1.0 ships after the external security review. Release gates that need people or outside systems are listed in the [spec](docs/spec.md) (section 14.2). New here? Read [The OunceMCP Book](docs/book/index.md).
+
+## Why
+
+Most MCP slowdowns don't come from the protocol. They come from loading every tool definition up front, returning large raw results, and making the model chain many small calls. OunceMCP makes the efficient design the default one:
+
+- **Context budgets:** token limits for tool definitions, the startup catalog, and each result, checked in CI.
+- **Automatic discovery:** switches from exposing every tool to search-then-call once the catalog is too large.
+- **Response shaping:** concise results by default, field selection, pagination, truncation notes, and handles for large data.
+- **Safe execution:** declared effects, deadlines, bounded retries, idempotent writes, and approvals.
+- **Visibility:** see exactly what the model received and what it cost.
+- **Optional audit:** measure any MCP server, including ones not built with OunceMCP.
+
+## Quickstart
+
+```bash
+pipx install "ouncemcp==1.0.0rc1"   # or: uv tool install --prerelease allow ouncemcp
+ouncemcp init notes-server && cd notes-server
+uv venv && uv pip install --prerelease allow -e ".[dev]"
+uv run pytest && uv run ouncemcp dev server.py
+```
+
+The full walkthrough is in [docs/quickstart.md](docs/quickstart.md). To learn the framework step by step, read [The OunceMCP Book](docs/book/index.md): one library server built across 15 chapters, every stage tested. A tool looks like this:
+
+```python
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from ouncemcp import Cursor, Detail, Effect, OunceServer, Paginated, ToolContext
+
+server = OunceServer("inventory")
+
+
+class SearchInput(BaseModel):
+    region: str = Field(description="Region, e.g. ap-south-1")
+    limit: int = Field(20, ge=1, le=50)
+    cursor: str | None = None
+
+
+class Resource(BaseModel):
+    id: str
+    name: str
+    status: str
+    tags: Annotated[dict[str, str] | None, Detail] = None  # only with response_format=detailed
+
+
+class SearchResult(BaseModel):
+    items: Annotated[list[Resource], Paginated]
+    next_cursor: Cursor = None
+
+
+@server.tool(name="inventory.search", effect=Effect.READ, deadline_ms=5_000)
+async def search(args: SearchInput, ctx: ToolContext) -> SearchResult:
+    """Find cloud resources in a region."""
+    rows = await load_resources(args.region)
+    page = ctx.page(rows, cursor=args.cursor, limit=args.limit)
+    return SearchResult(items=page.items, next_cursor=page.next_cursor)
+
+
+if __name__ == "__main__":
+    server.run()  # stdio; prints a token budget summary to stderr
+```
+
+What you get:
+
+- **Declared effects:** `effect` is required and maps to MCP `readOnlyHint` and `destructiveHint`.
+- **Typed inputs and outputs:** Pydantic models in, Pydantic models out, validated both ways.
+- **Compact schemas:** optional fields are advertised without the `anyOf`/`null` noise.
+- **Concise by default:** fields marked `Detail` are only returned when the agent asks for `response_format="detailed"`.
+- **Result budgets:** every result fits its token budget and still matches its output schema. Lists are trimmed first, then long strings, then optional fields, and the agent gets a note saying what was removed and how to get more. If the smallest valid result is still too large, the agent gets an `isError` result asking for a narrower call instead of broken JSON.
+- **Safe pagination:** mark the page list `Paginated` and the cursor `Cursor`, and use `ctx.page(...)`. If OunceMCP trims the page to fit the budget, it moves `next_cursor` so the next call resumes after the last item returned. No item is skipped or repeated. Lists are never trimmed below `min_items` (default 1). Cursors are signed: they expire, and only work for the same tool, caller and filters. Set `OUNCEMCP_CURSOR_KEYS` in production ([proposal 0003](docs/proposals/0003-signed-cursors.md)).
+- **Automatic discovery:** `OunceServer(discovery="auto")` (the default) sends every tool while the definitions fit `Budget.startup_tokens`. Above it, the server sends `search_tools`, `describe_tool` and `call_tool` instead (279 tokens whatever the catalog), plus any `pinned` tools. Search results come in three detail levels (`name`, `summary`, `full`) and only include tools the caller is authorized to use (`@server.tool(auth=...)`). Hiding a tool is not access control: the same check runs on a guessed name. `discovery="direct"` or `"search"` overrides the choice, and `await server.measure_recall(cases)` reports how often search finds the tools agents need. See [proposal 0006](docs/proposals/0006-discovery-modes.md).
+- **Categorized errors:** every failure is one of validation, authentication, permission, not found, rate limit, transient, ambiguous write or internal, with a `retryable` flag. Validation messages say how to fix the input without repeating it. Unexpected exceptions are never shown to the model: it gets a reference id and the details go to the log. Messages you write are redacted for URLs, addresses, hostnames, paths and credentials. Raise `InvalidInput`, `NotFound`, `RateLimited` and the other `OunceError` classes from handlers.
+- **Execution limits:** every call has a deadline (default 30 s) and is cancelled when it passes or the client cancels. Reads are retried a few times with bounded backoff inside the deadline, and writes never are. A write that times out is reported as ambiguous, not as failed. Request size, nesting depth and calls in flight per principal are bounded (`Limits`). See [proposal 0007](docs/proposals/0007-errors-and-execution-limits.md).
+- **Security and policy:** `ctx.identity` comes from the verified token only. `policy=` on the server or a tool decides who sees and calls it, on the declared effect, never on annotations. `audience=` refuses tokens issued for other servers, `passthrough_guard()` stops the caller's token from reaching upstream APIs, `ctx.cache` is partitioned by tenant, `ctx.issue_state` hands out handles and approvals bound to caller, request and expiry, and HTTP binds to loopback with `Host` and `Origin` checks ([proposal 0008](docs/proposals/0008-security-and-policy.md)).
+- **Safe writes:** `idempotency=True` runs a write once per caller and arguments, and a write that times out finishes in the background so a retry gets its result instead of writing twice. `approval="required"` with a `preview` asks a person first, through the client, and refuses when nobody can be asked ([safe writes](docs/guides/safe-writes.md)).
+- **Large results and slow work:** `OunceServer(handles=True)` adds `handles.read` and `jobs.get`. `await ctx.store_result(rows)` returns a handle to page, and `await ctx.start_job(work)` runs work in the background. Both work across replicas with a shared `RedisStore`.
+- **Resources and prompts:** `@server.resource(uri)` and `@server.prompt()` get the same budgets, policies and verified caller as tools.
+- **Migration and audit:** `OunceServer.wrap(existing_fastmcp_server)` adds all of the above without touching its tools, and `ouncemcp audit <url | file | -- command>` measures any MCP server ([migration guide](docs/guides/migrating-from-fastmcp.md)).
+- **Many servers:** `ouncemcp.client.Broker` connects a host to many servers as one catalog, with namespaced tools, cross-server search, schema checks, deadlines, failure isolation, and no cross-server authority from server output ([broker](docs/guides/client-broker.md)).
+- **Operations:** `OunceServer.from_config(name, "ouncemcp.toml")`, `/healthz`, `/readyz` and, with `metrics=True`, Prometheus `/metrics` ([deploying](docs/guides/deploying-http.md)).
+- **Traces:** `OunceServer(trace=MemorySink())` records each call's result tokens, latency, retries and outcome, redacted by default ([proposal 0009](docs/proposals/0009-traces.md)). `ouncemcp trace calls.jsonl` writes an HTML report you can search and filter ([proposal 0020](docs/proposals/0020-report-ui.md)), and `OTelSink()` exports spans to OpenTelemetry ([proposal 0018](docs/proposals/0018-trace-viewer.md)).
+- **Task suites:** `ouncemcp eval suite.yaml` runs YAML tasks against a server, judges outcomes on the server, and reports success, tool choice, tokens, latency and regressions against a baseline ([proposal 0019](docs/proposals/0019-eval-kit.md)).
+- **Composite tools:** `ctx.gather(...)` runs several upstream calls in one tool call. The example `inventory.cost_review` returns 651 tokens in 1 call where paging `inventory.search` takes 9,896 tokens over 8 calls.
+- **Testing:** `ouncemcp.testing.as_caller(...)` runs code as a verified caller, and `ouncemcp.eval.run_security_suite(server, cases)` probes for cross-tenant leaks, guessed names, cursor and handle reuse, replay, token passthrough and SSRF.
+- **Budget checks:** `ouncemcp check server.py` counts the tokens of every tool definition as the host receives it, and fails CI when a tool goes over budget or a lint error is found. It also reports which discovery mode the server will use and why. Every lint and error links to a page explaining it.
+
+```bash
+ouncemcp check examples/inventory/server.py
+ouncemcp context examples/inventory/server.py inventory.search
+ouncemcp context examples/inventory/server.py --html context.html   # every tool, as a page
+ouncemcp dev examples/inventory/server.py      # hot reload, live per-call token lines
+```
+
+Counts use `o200k_base` by default. Choose another tiktoken encoding with `OunceServer(tokenizer="cl100k_base")` or `ouncemcp check --tokenizer cl100k_base`, or pass your own counting function with `tokenizer=fn, tokenizer_name="my-tokenizer-v1"`. Every report names the tokenizer it used ([proposal 0004](docs/proposals/0004-pluggable-tokenizer.md)).
+
+`ouncemcp audit` is the optional command for measuring any server. `ouncemcp eval` runs task suites, with the replay model or real models through OpenRouter, `ouncemcp bench` compares servers across models, and `ouncemcp trace` reads traces.
+
+## Benchmark (M3)
+
+Two pilot servers against their plain FastMCP equivalents: four models (Claude Haiku 5.5, Claude Sonnet 5.5, GPT-5.4 mini, DeepSeek V4.1 Flash), 21 tasks, 5 runs each, success judged on outcomes. See the [full results and caveats](benchmarks/results/m3-bench.md).
+
+| | Inventory (large results) | Ticketing (writes, small results) |
+| --- | --- | --- |
+| Tokens per task, OunceMCP vs plain | 58–85% fewer | 17–40% more |
+| Task success, OunceMCP vs plain | 100% vs 75–100% | 100% vs 68–70% |
+| Tool definitions, OunceMCP vs plain | 584 vs 244 tokens | 649 vs 366 tokens |
+
+On these small servers the definitions are larger, mostly from output schemas. PERF-6, revised for small servers (definitions at most 2× plain, no drop in success), is met for ticketing and missed for inventory at 2.4× ([proposal 0027](docs/proposals/0027-benchmark.md)). On the plain ticketing server every model skipped the approval, deleted without permission and read another team's ticket.
+
+## M0 results
+
+Measured on the inventory example with the `o200k_base` tokenizer. Full method and caveats are in [docs/m0-report.md](docs/m0-report.md).
+
+| | OunceMCP | Plain FastMCP |
+| --- | ---: | ---: |
+| Tool definitions (2 tools) | 488 tokens | 195 tokens |
+| Four-task session, definitions plus results | 1,510 tokens | 32,280 tokens |
+| Added server time per call, p50 / p95 | 0.14–0.44 ms / 0.07–0.47 ms (1.44 / 1.32 ms when truncating) | baseline |
+
+In M1, results that are trimmed must still match the output schema. Truncated calls now add 0.70 / 0.80 ms (p50 / p95) and other calls 0.14 to 0.31 ms. Shaping a 36,000-token result down to a 2,000-token budget takes 7.3 ms. See [proposal 0002](docs/proposals/0002-schema-safe-shaping-and-pagination.md) and `benchmarks/scripts/m1_truncation.py`.
+
+Typed output schemas make definitions larger. Results are where the savings come from. Output schemas can be set to `"on"` (default), `"off"` or `"auto"` for a server (`output_schemas=`) or one tool (`output_schema=`). In M1, `"off"` gave 247 tokens for this example, and `"auto"`, which drops a schema only where it would put a definition over the per-tool target, gave 378. `ouncemcp check` reports the output-schema share of definition tokens (241 of 504 in the current example) and states which fields it counts: `name`, `description`, `inputSchema` and `outputSchema`, not `title`, `annotations` or `_meta` ([proposal 0005](docs/proposals/0005-counting-scope-and-output-schema-modes.md)).
+
+## Repository layout
+
+```text
+src/ouncemcp/
+  core/        capabilities, budgets, response shaping, token accounting, errors, lints,
+               resources and prompts, config file
+  security/    identity, policy, audience and passthrough, caches, bound state, HTTP
+               defaults, stdio policy, URL checks
+  discovery/   direct and search discovery modes
+  execution/   deadlines, retries, limits, middleware, store, idempotency, approvals,
+               handles and jobs
+  trace/       per-call traces, redaction and metrics
+  eval/        conformance target, security test catalog and agent task suites
+  cli/         init, dev, check, context, audit, eval, trace (bench planned)
+  client/      reference client broker
+  audit/       optional audit command
+  testing.py   as_caller and make_token for tests
+examples/      pilot servers: inventory, ticketing, report, markitdown migration
+benchmarks/    servers, tasks, scripts, published results
+docs/          specification, research, concepts, guides, proposals
+tests/
+```
+
+## Roadmap
+
+| Milestone | Scope | Status |
+| --- | --- | --- |
+| M0: core spike | `OunceServer`, typed tools with effects, token counting, result budgets, one example server | Built ([M0 report](docs/m0-report.md)) |
+| M1: v0.1 | Framework core, automatic discovery, errors, security, `init`/`dev`/`check`/`context`, docs | Built |
+| M2: v0.2 | Safe writes, client broker, migration guide, pilots, optional `audit` | Built ([M2 report](docs/m2-report.md)) |
+| M3: v0.5 | Eval kit, trace viewer, public benchmark, launch | Built ([benchmark](benchmarks/results/m3-bench.md)); launch waits on the repository going public |
+| M4: v1.0 | Security review, host compatibility matrix, stable API, the book | API frozen ([0029](docs/proposals/0029-api-freeze.md)), all release gates checked, release workflow ready ([M4 report](docs/m4-report.md)); waiting on the external security review |
+
+The full plan is in [docs/spec.md](docs/spec.md), and the supporting research is in [docs/performance-research.md](docs/performance-research.md).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run pytest
+uv run ruff check .
+uv pip install -e ".[docs]" && uv run mkdocs serve   # documentation site
+python benchmarks/scripts/m0_compare.py     # token comparison
+python benchmarks/scripts/m0_overhead.py    # per-call overhead
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).
+
+## License
+
+[Apache-2.0](LICENSE)