redacted-context-mcp 0.7.0__tar.gz

redacted_context_mcp-0.7.0/.github/workflows/test.yml

@@ -0,0 +1,64 @@
+name: test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e .
+      - run: python -m unittest discover -s tests -p 'test_*.py'
+      - run: python -m py_compile src/redacted_context_mcp/core.py src/redacted_context_mcp/server.py
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Smoke test built wheel
+        shell: python
+        run: |
+          import glob
+          import os
+          import subprocess
+          import sys
+
+          wheels = glob.glob("dist/*.whl")
+          if len(wheels) != 1:
+              raise SystemExit(f"Expected one wheel, found {wheels!r}")
+          subprocess.check_call([sys.executable, "-m", "venv", "wheel-smoke"])
+          python = os.path.join("wheel-smoke", "bin", "python")
+          subprocess.check_call([python, "-m", "pip", "install", "--upgrade", "pip"])
+          subprocess.check_call([python, "-m", "pip", "install", wheels[0]])
+          bin_dir = os.path.join("wheel-smoke", "bin")
+          subprocess.check_call([os.path.join(bin_dir, "redctx"), "--help"])
+          subprocess.check_call([os.path.join(bin_dir, "redctx-mcp"), "--help"])

redacted_context_mcp-0.7.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.chloe/
+.agent-context-redactor.toml
+.redacted-context-mcp/
+agent-workdir/work/*
+!agent-workdir/work/.gitkeep

redacted_context_mcp-0.7.0/ARCHITECTURE.md

@@ -0,0 +1,134 @@
+# Architecture
+
+`redacted-context-mcp` exposes a private local knowledgebase through a narrow
+redaction layer. The default MCP surface is read-only; controlled writes are
+available only when the server is started with explicit write flags. The project
+is intentionally small: it avoids runtime dependencies, stores no persistent
+index, and keeps all sensitive configuration local.
+
+## Data Flow
+
+```text
+agent workspace
+  -> MCP client or redctx CLI
+    -> redaction layer
+      -> private source root
+        -> redacted text plus opaque path references
+```
+
+The agent should start from a neutral workspace that does not contain the raw
+private context files. The MCP server receives tool calls, resolves paths inside
+the configured root, reads allowed text files, redacts output, and returns only
+the redacted result. If controlled writes are enabled, generated redacted text
+can be rehydrated locally and written under a configured private-root
+subdirectory.
+
+## Core Boundaries
+
+- The server is read-only by default.
+- Controlled MCP writes require `--enable-writes` and are constrained to
+  `--write-subdir`.
+- Path resolution is constrained to the configured root.
+- Known private/cache paths and binary-like files are excluded by default.
+- File navigation uses local-salted HMAC ids such as `@p_1a2b3c4d5e6f`.
+- Filesystem traversal starts from validated paths, skips symlink and reparse
+  entries, and revalidates paths before content reads and opaque-id resolution.
+- Content reads compare file metadata before and after reading to detect common
+  substitutions, but the project remains a guardrail rather than a hard
+  concurrent-mutation sandbox.
+- Redacted files are available as MCP resources with `redctx://p_<id>` URIs.
+- MCP resource content is cached only after redaction and is bounded by byte
+  limits.
+- The stdio server supports both stateless MCP `2026-07-28` requests and the
+  legacy initialization-based protocol through `2025-11-25`.
+- Opaque path references are explicit request arguments rather than implicit
+  protocol-session state. In-memory path and content indexes are reconstructable
+  caches; the persistent vault salt is durable server configuration.
+- Redaction happens before file content, file paths, search results, bundles,
+  and GitHub issue text are returned.
+
+## Module Layout
+
+- `core.py`: CLI commands, parser setup, and compatibility re-exports.
+- `server.py`: minimal stdio MCP JSON-RPC server.
+- `defaults.py`: default limits, allow lists, exclude lists, and compiled
+  patterns.
+- `models.py`: shared dataclasses.
+- `redaction.py`: text/path redaction logic.
+- `config.py`: local TOML config loading and validation.
+- `paths.py`: root-constrained path resolution and opaque path ids.
+- `filesystem.py`: read-only filesystem traversal and text-file detection.
+- `discovery.py`: local Ollama discovery workflow and post-processing.
+- `github.py`: read-only GitHub issue access through neutral aliases.
+
+## Controlled Write Path
+
+`redctx_submit_doc` is hidden unless the server starts with `--enable-writes`.
+When enabled, it accepts generated redacted text, rebuilds the local
+rehydration map from the private source root, rejects unresolved placeholders,
+and writes the restored document only under `--write-subdir`.
+
+The write tool does not accept arbitrary workspace file paths. It accepts text
+content directly and a relative target path. Overwrites require an explicit
+`overwrite` argument. Tool results return only redacted path metadata and opaque
+ids.
+
+No-overwrite writes are published from a same-directory temporary file without
+replacing an existing target where hard-link publication is available. Explicit
+overwrites use same-directory `os.replace`. Directory durability fsync is
+best-effort and POSIX-only.
+
+## Redaction Model
+
+Redaction combines configured exact terms with conservative generic patterns:
+
+- configured clients, organizations, people, and sensitive terms;
+- email addresses, URLs, phone numbers, handles, secrets, tokens, common
+  personal identifiers, IP addresses, UUIDs, and domains;
+- organization suffix patterns;
+- multi-token proper names;
+- stricter titlecase/acronym handling in `strict` mode.
+
+The allow list prevents common public technologies and generic vocabulary from
+being over-redacted. Project-specific allow-list entries belong in the local
+`.agent-context-redactor.toml`, not in source control.
+
+Placeholders are deterministic 128-bit HMAC aliases derived from the local
+salt, for example `[PERSON_1a2b3c4d5e6f7890a1b2c3d4e5f60718]`. The same raw
+value maps to the same placeholder for one private config without exposing the
+raw value. Placeholder collisions are detected and fail closed instead of
+building an ambiguous rehydration map.
+
+## Configuration
+
+The local `.agent-context-redactor.toml` file is intentionally ignored by git.
+It may contain exact client names, stakeholder names, project codenames, private
+repo names, and token environment variable names.
+
+If a config or environment salt is not supplied, the loader creates or reuses a
+random 256-bit vault salt in user-local state. Missing state creates a new
+random salt. Existing empty, malformed, or root-contained state fails closed
+instead of rotating aliases silently. `redctx doctor` reports the salt source.
+
+`redctx discover` can draft that file with a local Ollama model. It is a setup
+command for a human operator, not an MCP tool, because its output intentionally
+contains raw sensitive terms.
+
+## GitHub Issue Access
+
+GitHub repositories are configured by neutral aliases under
+`[github.repos.<alias>]`. The alias is what the agent sees. Raw owner/repo names
+and author logins are not printed in tool output. Author aliases are HMACs over
+the local vault salt, repo alias, and login so they are not linkable across
+vaults or repo aliases.
+
+The GitHub integration is read-only and uses the token environment variable
+named in local config.
+
+## Security Posture
+
+This project is a privacy guardrail, not a hard isolation boundary. If the agent
+process can read the private source folder directly, prompts and MCP routing
+are not enough. For stronger enforcement, run the agent as a separate OS user or
+inside a container that cannot access the private folder directly, and expose
+only the redacted MCP server.

redacted_context_mcp-0.7.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+## 0.7.0
+
+Security hardening release.
+
+- Never serves the redaction config, configured term files, `.env*`, `*.key`,
+  `*.pem`, or `*.crt` through redacted tools, even with `--include-private`.
+- Redacts bare long hex strings (the persisted vault-salt shape) and
+  `salt`-keyed assignments as secrets in the default detector profile, closing
+  a vault-salt disclosure path.
+- Adds Google API key (`AIza...`) detection to the default secret patterns.
+- Screens user-supplied search regexes for catastrophic-backtracking shapes
+  and rejects them; MCP searches now enforce a server-side operation deadline
+  checked per file and per matching line.
+- Caps MCP stdio request line size so clients cannot exhaust server memory.
+- Controlled-write rehydration maps no longer scan the write subdirectory,
+  preventing agent-written content from poisoning later rehydration.
+- Verifies `redctx_submit_doc` output re-redacts consistently on read-back and
+  rejects writes that would leak restored values past redaction boundaries.
+- Refuses non-loopback plain-http Ollama discovery endpoints unless
+  `--allow-remote-endpoint` is passed.
+- Truncation no longer splits redaction placeholders mid-token.
+- Matches user-supplied search regexes in an isolated, killable child process
+  so catastrophic patterns can never hang the single-threaded server; the
+  static backtracking screen now also rejects ambiguous dots, negated
+  classes, nested-group hazards, and high-repetition bounded quantifiers.
+- Case-folds never-serve matching so `.ENV`, `server.PEM`, and similar
+  case-mangled variants are refused on case-insensitive filesystems, and
+  protects an explicit `--config` file like the default config.
+- Redacts salt assignments with short, spaced, or triple-quoted values,
+  256-bit-plus hex runs of any length, and underscore-qualified secret
+  assignments such as `DB_PASSWORD=...`; treats configured GitHub
+  owner/repo identifiers as redaction terms.
+- Verifies `redctx_submit_doc` output against both strict and balanced
+  redaction modes and builds rehydration maps solely from the scanned
+  corpus, closing adjacent-placeholder and interactive-read aliasing gaps.
+- Reports an error for oversized unterminated stdio request lines and accepts
+  `localhost.` (trailing-dot) Ollama endpoints.
+
+## 0.6.0
+
+- Adds dual-era MCP support for stateless protocol version `2026-07-28` while
+  preserving the legacy initialization flow through `2025-11-25`.
+- Adds `server/discover`, per-request modern metadata validation, structured
+  unsupported-version errors, modern result metadata, and cache hints.
+- Keeps opaque path ids, the redacted content cache, and the persistent vault
+  salt independent of MCP protocol sessions.
+
+## 0.5.0
+
+- Adds a reusable document-discovery and monotonic TOML-update API plus the
+  `redctx discover-update` JSONL CLI for local Git-hook integrations.
+- Rejects discovery values absent from their source document and supports
+  fail-closed document-size limits and seed-only config merges.
+- Adds extended-profile detection for common `sp-`, `svc-`, and `sa-` service
+  account identifiers.
+
+## 0.4.0
+
+- Revalidates stale opaque ids, rejects detected symlink/reparse substitutions,
+  and verifies file metadata around content reads where the standard library
+  allows.
+- Changes default vault-salt handling so missing state creates and persists a
+  new random salt, while malformed or unsafe existing state fails closed instead
+  of silently rotating aliases.
+- Adds per-call redaction receipts, bounded operation budgets, and a bounded
+  redacted-only MCP resource cache.
+- Preserves line counts when multi-line secrets are redacted before search
+  output is split into lines.
+- Speeds ordinary no-match literal searches by using a raw-byte prefilter while
+  keeping placeholder-sensitive and regex searches on the full redaction path.
+- Adds security regression tests, UTF-8 stdio handling, SHA-pinned CI actions,
+  and CI package validation for the 0.4.0 release.
+
+## 0.3.0
+
+- Adds redacted MCP resources with `redctx://p_<id>` URIs alongside the
+  existing `redctx_*` tools.
+- Updates MCP protocol support to `2025-11-25` and advertises read-only tool
+  annotations with stricter input schemas.
+- Changes path ids to local-salted HMAC ids to make common filename guesses
+  harder.
+- Changes placeholders from order-based counters to deterministic HMAC aliases,
+  such as `[PERSON_1a2b3c4d]`.
+- Expands generic redaction coverage for secrets, tokens, common personal
+  identifiers, IP addresses, UUIDs, and domains.
+- Adds a CLI-only `redctx rehydrate` command for restoring redacted file or
+  folder exports locally from the private source root.
+- Adds opt-in MCP `redctx_submit_doc` controlled writes for rehydrating generated
+  redacted documents into a configured private-root subdirectory.
+- Fixes `redctx discover --format json`.
+- Handles UTF-8 BOMs in TOML config and text file reads.
+- Adds regression coverage for discovery JSON output, MCP resources, stricter
+  tool schemas, salted ids, deterministic placeholders, and redaction leak
+  benchmarks.
+
+## 0.1.0
+
+- Initial release candidate.
+- Adds `redctx` CLI for redacted local file discovery, read, search, stat, and
+  bundle operations.
+- Adds `redctx-mcp` stdio MCP server exposing `redctx_*` tools for coding
+  agents.
+- Supports opaque stable path ids, local TOML redaction configuration, and
+  no-dependency runtime operation.
+- Adds `redctx discover`, an offline setup command that uses a local Ollama
+  model to draft raw redaction terms for human review.
+- Discovery output is generically post-processed to reduce noisy `terms`
+  entries and move public/default-allowed technical vocabulary to `allow`.
+- Adds optional redacted GitHub issue access through configured neutral repo
+  aliases and MCP tools.

redacted_context_mcp-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+This project is security-adjacent, so small changes should still be treated with
+care. Keep the package boring, explicit, and easy to audit.
+
+## Local Setup
+
+```sh
+python3 -m pip install -e .
+python3 -m unittest discover -s tests -p 'test_*.py'
+python3 -m py_compile src/redacted_context_mcp/core.py src/redacted_context_mcp/server.py
+```
+
+Optional release tooling:
+
+```sh
+python3 -m pip install -e '.[dev]'
+python3 -m build
+python3 -m twine check dist/*
+```
+
+## Standards
+
+- Keep runtime dependencies at zero unless there is a strong reason to add one.
+- Keep tool output redacted by default and avoid raw paths, owner/repo names,
+  author logins, tokens, or sensitive config values.
+- Prefer clear, local functions over framework abstractions.
+- Keep examples neutral. Do not use real client names, employer names,
+  stakeholder names, internal project names, or domain-specific customer
+  technology defaults in tracked files.
+- Treat `.agent-context-redactor.toml` and generated discovery output as private
+  local files.
+
+## Privacy Checks
+
+Before publishing or opening a PR, run:
+
+```sh
+rg -n -i '(<your-company>|<client-name>|<private-repo>|<token-prefix>)' .
+```
+
+Substitute terms that are relevant to your environment before running the scan.
+Some placeholders appear intentionally in docs and examples. Replace anything
+that refers to a real organization, client, person, private repo, token, or
+project codename.
+
+## Release Checks
+
+At minimum, a release must pass:
+
+```sh
+python3 -m unittest discover -s tests -p 'test_*.py'
+python3 -m py_compile src/redacted_context_mcp/core.py src/redacted_context_mcp/server.py
+python3 -m build
+python3 -m twine check dist/*
+```

redacted_context_mcp-0.7.0/LICENSE

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