PkgFoundry
Catalog PyPI
Back to packageRELEASE DETAILS

0.72.0

PyPI

3tears-mcp

Shared MCP framework: McpServer + McpTool + PlatformHttpClient + per-tool RBAC backed by mcp_tool_grants and the task-02 epoch broadcast

Published20 Oct 2026
Direct dependencies10
Transitive dependenciesNot calculated

README

Version 0.72.0 documentation

3tears-mcp

Shared MCP (Model Context Protocol) framework. Per-product MCP servers compose this framework instead of reimplementing stdio transport, JWT auth, error mapping, and per-tool RBAC.

What's in here

ModuleResponsibility
serverMcpServer -- wraps the official mcp.server.Server. Owns tool registration, RBAC gating before handler dispatch, structured error mapping per the MCP spec.
toolMcpTool dataclass (name, description, input_schema, required_permission, handler) and register_tool decorator.
http_clientPlatformHttpClient -- typed httpx client with JWT login + refresh-on-401. Used by both MCP server tool handlers (calling /api/v1/...) and CLI scripts. One HTTP-client implementation, two transports.
authIdentity dataclass + IdentityProvider Protocol + EnvVarIdentityProvider (stdio impl). Authorizer Protocol + LocalGrantAuthorizer (default impl backed by McpToolGrantCollection).
rbacMcpToolGrantCollection -- BaseCollection over mcp_tool_grants. Exposes the in-memory grant cache that LocalGrantAuthorizer consults.
migrations/v01_create_mcp_tool_grants -- platform-scope DDL. Consumers register via MigrationRunner.register(epoch_pkg) (same shape as threetears.epoch).

RBAC model

Per-tool, default-deny. Each McpTool declares a required_permission string (e.g. "conversations.read", "audit.read"). On every dispatch:

  1. The framework calls Authorizer.allows(identity, required_permission).
  2. LocalGrantAuthorizer checks whether the caller's identity matches an active grant in McpToolGrantCollection for the requested permission.
  3. If denied, the framework returns a structured MCP error to the client (not a Python exception in the response body).

The configured admin identity (env-var creds in the stdio impl) is auto-granted in memory at server startup. The grant is logged but NOT written to mcp_tool_grants. This keeps the table truthful (only operator-added grants live there).

Grant changes propagate cross-pod via the mcp.rbac epoch broadcast. LocalGrantAuthorizer subscribes to Subjects.mcp_rbac_epoch() via an EpochListener; on bump it reloads the grant cache from L3. Cold-start primes from EpochClient.current(...). Missed broadcasts recover via the standard pull-on-stale path.

Identity in v1

EnvVarIdentityProvider returns one fixed Identity for the lifetime of the server, derived from env-var credentials. v2 (HTTP transport + per-call bearer-token identity) plugs in by adding a BearerTokenIdentityProvider; the rest of the framework is unchanged. The Authorizer.allows(identity, permission) interface is unchanged between v1 and v2.

Stdio transport discipline

Every byte on stdout/stderr from a stdio MCP server confuses the client. The framework configures logging to a file or to NATS; no module under threetears.mcp should write to sys.stdout / sys.stderr. An AST enforcement test guards this.

Postgres backing

CREATE TABLE IF NOT EXISTS mcp_tool_grants (
    grant_id UUID PRIMARY KEY,
    principal_type TEXT NOT NULL,   -- 'user' | 'group' | 'role'
    principal_id UUID NOT NULL,
    tool_name TEXT NOT NULL,
    permission TEXT NOT NULL,
    date_created TIMESTAMPTZ NOT NULL DEFAULT now()
);

Mutation paths (admin POST /admin/mcp/grants, DELETE /admin/mcp/grants/{id}) bump Subjects.mcp_rbac_epoch() after the row commit; sibling pods reload via the epoch listener.

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 10

Native requirements
10 direct targetsNot calculated transitive count
Package / targetRequirementRelationship
3tears-epoch
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
3tears-epoch<0.73.0,>=0.72.0runtime
3tears-nats
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
3tears-nats<0.73.0,>=0.72.0runtime
3tears-observe
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
3tears-observe<0.73.0,>=0.72.0runtime
3tears
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
3tears<0.73.0,>=0.72.0runtime
httpx
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
httpx>=0.27runtime
mcp
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
mcp>=1.27runtime
pydantic
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
pydantic>=2runtime
starlette
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
starlette>=0.40runtime
uuid-utils
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
uuid-utilsruntime
uvicorn
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.14",
  "evaluation": "NOT_EVALUATED"
}
uvicorn>=0.30runtime

Distribution files

2 collected
3tears_mcp-0.72.0-py3-none-any.whl

bdist_wheel · 35.26 KB · Python py3

Source file
3tears_mcp-0.72.0.tar.gz

sdist · 56.82 KB · Python source

Source file

Repository

ACCESSIBLE
pacepace/3tears

Shared repository data · GitHub

License detected in repository
MIT
License branch / ref
develop
Last push
20 Oct 2026
Archived
No
Contributor identities
— · partial collection

Public sponsor counts have not been collected. These signals belong to the repository owner.

Downloads & popularity

0count
Gauge · observed snapshots20 Oct 2026
10.50
2026-10-20: 0 · observed 2026-10-20T17:18:19.8928356Z
20 Oct20 Oct

github · 1 observations shown. Missing days are unknown.

View observed values
Date / source periodValueObserved at
2026-10-2002026-10-20T17:18:19.8928356Z

Metadata history

Meaningful changes
Current collected state Current

Observed since 20 Oct, 15:38 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:cdb3f00393c26fa976dc3a085f0b19019f9bdcdcfd1455e9c28b6568fa64180c

Other collected versions

View all collected versions →