tracenor-mcp 1.0__tar.gz

tracenor_mcp-1.0/.gitignore

@@ -0,0 +1,153 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+.venv/
+.artifacts/
+__pycache__/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+.output
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp directory
+.temp
+
+# Sveltekit cache directory
+.svelte-kit/
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Firebase cache directory
+.firebase/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# pnpm
+.pnpm-store
+
+# Turborepo cache
+.turbo/
+
+# Reproducible benchmark output is uploaded by CI; selected release evidence is
+# copied to docs/benchmarks intentionally.
+artifacts/benchmarks/
+
+# yarn v3
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Vite files
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+.vite/

tracenor_mcp-1.0/.python-version

@@ -0,0 +1 @@
+3.12

tracenor_mcp-1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: tracenor-mcp
+Version: 1.0
+Summary: Protocol-clean STDIO MCP connector for Tracenor.
+Project-URL: Homepage, https://github.com/i9clouds/sharedmemoryai/tree/main/packages/mcp-server
+Project-URL: Repository, https://github.com/i9clouds/sharedmemoryai.git
+Project-URL: Issues, https://github.com/i9clouds/sharedmemoryai/issues
+Author: i9clouds
+License: UNLICENSED
+Keywords: mcp,model-context-protocol,stdio,tracenor
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp<2,>=1.26
+Description-Content-Type: text/markdown
+
+# Tracenor MCP STDIO connector
+
+Install the public package with uv:
+
+```sh
+uv tool install tracenor-mcp
+```
+
+Then register `tracenor-mcp` as an STDIO MCP server in your host. It requires
+`SHAREDMEMORY_API_URL` and `SHAREDMEMORY_API_KEY`; see the full
+[configuration guide](../../docs/mcp-stdio.md).
+
+`tracenor-mcp` exposes four tools to an MCP-capable local host:
+
+- `get_active_context`
+- `search_memories`
+- `propose_memory`
+- `create_approved_memory`
+
+The process owns the Git collector. Agents never select a workspace, vault,
+repository, repository root or trusted Git metadata. The API determines which
+vaults are eligible from the authenticated API key, platform permissions and
+the trusted local Git detection.
+
+See [`docs/mcp-stdio.md`](../../docs/mcp-stdio.md) for host setup and security
+requirements.

tracenor_mcp-1.0/README.md

@@ -0,0 +1,26 @@
+# Tracenor MCP STDIO connector
+
+Install the public package with uv:
+
+```sh
+uv tool install tracenor-mcp
+```
+
+Then register `tracenor-mcp` as an STDIO MCP server in your host. It requires
+`SHAREDMEMORY_API_URL` and `SHAREDMEMORY_API_KEY`; see the full
+[configuration guide](../../docs/mcp-stdio.md).
+
+`tracenor-mcp` exposes four tools to an MCP-capable local host:
+
+- `get_active_context`
+- `search_memories`
+- `propose_memory`
+- `create_approved_memory`
+
+The process owns the Git collector. Agents never select a workspace, vault,
+repository, repository root or trusted Git metadata. The API determines which
+vaults are eligible from the authenticated API key, platform permissions and
+the trusted local Git detection.
+
+See [`docs/mcp-stdio.md`](../../docs/mcp-stdio.md) for host setup and security
+requirements.

tracenor_mcp-1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "tracenor-mcp"
+version = "1.0"
+description = "Protocol-clean STDIO MCP connector for Tracenor."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "UNLICENSED" }
+authors = [{ name = "i9clouds" }]
+keywords = ["mcp", "model-context-protocol", "stdio", "tracenor"]
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "httpx>=0.28,<1",
+  "mcp>=1.26,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/i9clouds/sharedmemoryai/tree/main/packages/mcp-server"
+Repository = "https://github.com/i9clouds/sharedmemoryai.git"
+Issues = "https://github.com/i9clouds/sharedmemoryai/issues"
+
+[project.scripts]
+tracenor-mcp = "tracenor_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8.3,<9"]
+
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tracenor_mcp"]

tracenor_mcp-1.0/src/tracenor_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Tracenor's local-only STDIO MCP connector."""
+
+__version__ = "1.0"

tracenor_mcp-1.0/src/tracenor_mcp/server.py

@@ -0,0 +1,411 @@
+"""Protocol-clean STDIO MCP server for Tracenor."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+from uuid import UUID, uuid4
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, TextContent
+
+from . import __version__
+
+MEMORY_TYPES = {
+    "decision",
+    "constraint",
+    "pattern",
+    "preference",
+    "context",
+    "runbook",
+    "incident",
+    "lesson_learned",
+}
+MEMORY_STATUSES = {"proposed", "active", "rejected", "superseded", "archived"}
+ERROR_CODES = {
+    "validation_error",
+    "invalid_api_key",
+    "invalid_session",
+    "provisioning_pending",
+    "context_unavailable",
+    "not_found",
+    "quota_exceeded",
+    "conflict",
+    "target_ambiguous",
+    "write_target_unresolved",
+    "invalid_transition",
+}
+API_KEY_PATTERN = re.compile(r"^sm_live_[a-z0-9]{12}_[A-Za-z0-9_-]{43}$")
+SPACE_SLUG_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+GITHUB_SEGMENT_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_.-]*$", re.IGNORECASE)
+CANONICALIZATION_VERSION = 1
+
+
+class ConfigError(ValueError):
+    """Raised without including credential material in the message."""
+
+    def __init__(self) -> None:
+        super().__init__("invalid_mcp_config")
+
+
+@dataclass(frozen=True)
+class Config:
+    api_url: str
+    api_key: str
+    timeout_seconds: float
+
+
+def load_config(environment: dict[str, str] | None = None) -> Config:
+    environment = environment or dict(os.environ)
+    raw_url = environment.get("SHAREDMEMORY_API_URL")
+    api_key = environment.get("SHAREDMEMORY_API_KEY")
+    if raw_url is None or api_key is None or not API_KEY_PATTERN.fullmatch(api_key):
+        raise ConfigError()
+    parsed = urlparse(raw_url)
+    if (
+        parsed.scheme != "https"
+        or not parsed.netloc
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ConfigError()
+    raw_timeout = environment.get("SHAREDMEMORY_TIMEOUT_MS", "10000")
+    if not raw_timeout.isdigit() or not 1 <= int(raw_timeout) <= 60_000:
+        raise ConfigError()
+    return Config(
+        api_url=raw_url if raw_url.endswith("/") else f"{raw_url}/",
+        api_key=api_key,
+        timeout_seconds=int(raw_timeout) / 1000,
+    )
+
+
+async def run_git(cwd: str, *args: str) -> tuple[str, str]:
+    try:
+        process = await asyncio.create_subprocess_exec(
+            "git",
+            *args,
+            cwd=cwd,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        stdout, _ = await asyncio.wait_for(process.communicate(), timeout=2)
+    except (OSError, TimeoutError):
+        return "failed", ""
+    if process.returncode != 0 or len(stdout) > 64 * 1024:
+        return "failed", ""
+    return "ok", stdout.decode("utf-8", errors="replace")
+
+
+def one_line(value: str) -> str | None:
+    lines = [line.strip() for line in value.splitlines() if line.strip()]
+    return lines[0] if len(lines) == 1 else None
+
+
+def canonicalize_remote(remote: str) -> tuple[str, str] | None:
+    candidate = remote.strip()
+    if not candidate or any(character.isspace() or ord(character) < 32 for character in candidate):
+        return None
+    match = re.fullmatch(r"(?:[^@/:]+@)?([^/:]+):(.+)", candidate)
+    if match and "://" not in candidate:
+        hostname, path = match.group(1), f"/{match.group(2)}"
+    else:
+        parsed = urlparse(candidate)
+        if parsed.scheme not in {"https", "http", "ssh"} or not parsed.hostname:
+            return None
+        try:
+            port = parsed.port
+        except ValueError:
+            return None
+        if port and not (
+            (parsed.scheme == "https" and port == 443)
+            or (parsed.scheme == "http" and port == 80)
+            or (parsed.scheme == "ssh" and port == 22)
+        ):
+            return None
+        hostname, path = parsed.hostname, parsed.path
+    if hostname.lower() != "github.com":
+        return None
+    segments = [segment for segment in path.rstrip("/").removesuffix(".git").split("/") if segment]
+    if len(segments) != 2 or any(
+        not GITHUB_SEGMENT_PATTERN.fullmatch(segment) or ".." in segment
+        for segment in segments
+    ):
+        return None
+    canonical = f"github.com/{segments[0].lower()}/{segments[1].lower()}"
+    return canonical, hashlib.sha256(canonical.encode()).hexdigest()
+
+
+async def detect_local_git_context() -> dict[str, Any]:
+    root = os.environ.get("SHAREDMEMORY_REPO_PATH", "").strip() or os.getcwd()
+    status, output = await run_git(root, "rev-parse", "--show-toplevel")
+    worktree = one_line(output) if status == "ok" else None
+    if worktree is None:
+        return unavailable("not_detected")
+    status, output = await run_git(worktree, "remote")
+    remotes = [line.strip() for line in output.splitlines() if line.strip()] if status == "ok" else []
+    if not remotes:
+        return unavailable("not_detected")
+    status, output = await run_git(worktree, "symbolic-ref", "--quiet", "--short", "HEAD")
+    branch = one_line(output) if status == "ok" else None
+    remote: str | None = None
+    if branch:
+        status, output = await run_git(worktree, "config", "--get", f"branch.{branch}.remote")
+        upstream = one_line(output) if status == "ok" else None
+        if upstream in remotes:
+            remote = upstream
+    if remote is None:
+        remote = "origin" if "origin" in remotes else remotes[0] if len(remotes) == 1 else None
+    if remote is None:
+        return unavailable("ambiguous")
+    status, output = await run_git(worktree, "remote", "get-url", remote)
+    raw_remote = one_line(output) if status == "ok" else None
+    identity = canonicalize_remote(raw_remote) if raw_remote else None
+    if identity is None:
+        return unavailable("ambiguous")
+    canonical, fingerprint = identity
+    return {
+        "status": "detected",
+        "canonical": canonical,
+        "fingerprint": fingerprint,
+        "canonicalization_version": CANONICALIZATION_VERSION,
+    }
+
+
+def unavailable(status: str) -> dict[str, None | str]:
+    return {
+        "status": status,
+        "canonical": None,
+        "fingerprint": None,
+        "canonicalization_version": None,
+    }
+
+
+class ApiClient:
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    async def request(self, path: str, body: dict[str, Any], is_write: bool, request_id: str) -> dict[str, Any]:
+        try:
+            async with httpx.AsyncClient(timeout=self.config.timeout_seconds) as client:
+                response = await client.post(
+                    f"{self.config.api_url}{path}",
+                    json=body,
+                    headers={
+                        "Authorization": f"Bearer {self.config.api_key}",
+                        "Content-Type": "application/json",
+                        "X-Request-Id": request_id,
+                    },
+                )
+        except httpx.TimeoutException as error:
+            raise ApiError("request_timeout", "unknown" if is_write else "not_started", request_id) from error
+        except httpx.HTTPError as error:
+            raise ApiError("network_error", "unknown" if is_write else "not_started", request_id) from error
+        server_request_id = response.headers.get("x-request-id", request_id)
+        if response.is_error:
+            code = "api_error"
+            try:
+                candidate = response.json().get("error", {}).get("code")
+                if candidate in ERROR_CODES:
+                    code = candidate
+            except (ValueError, AttributeError):
+                pass
+            raise ApiError(code, "not_started", server_request_id)
+        try:
+            payload = response.json()
+        except ValueError as error:
+            raise ApiError("invalid_api_response", "not_started", server_request_id) from error
+        if not isinstance(payload, dict):
+            raise ApiError("invalid_api_response", "not_started", server_request_id)
+        return payload
+
+
+@dataclass(frozen=True)
+class ApiError(Exception):
+    code: str
+    outcome: str
+    request_id: str
+
+
+def successful(payload: dict[str, Any]) -> dict[str, Any]:
+    return payload
+
+
+def failed(code: str, text: str, request_id: str | None = None, idempotency_key: str | None = None) -> CallToolResult:
+    structured: dict[str, Any] = {"code": code}
+    if request_id:
+        structured["request_id"] = request_id
+    if idempotency_key:
+        structured["retry_with_same_idempotency_key"] = idempotency_key
+    return CallToolResult(
+        content=[TextContent(type="text", text=text)],
+        structuredContent=structured,
+        isError=True,
+    )
+
+
+def valid_space_slugs(value: list[str] | None) -> bool:
+    return value is None or all(
+        isinstance(slug, str) and 1 <= len(slug.strip()) <= 120 and SPACE_SLUG_PATTERN.fullmatch(slug.strip())
+        for slug in value
+    )
+
+
+def valid_types(value: list[str] | None) -> bool:
+    return value is None or all(item in MEMORY_TYPES for item in value)
+
+
+mcp = FastMCP("tracenor-mcp", json_response=True, log_level="ERROR")
+# FastMCP delegates server metadata to the underlying protocol server; pin the
+# public connector version instead of exposing the SDK version in initialize.
+mcp._mcp_server.version = __version__
+
+
+@mcp.tool()
+async def get_active_context(
+    space_slugs: list[str] | None = None,
+    types: list[str] | None = None,
+    limit: int = 30,
+) -> Any:
+    """Get active memories allowed for this local repository context."""
+    if not valid_space_slugs(space_slugs) or not valid_types(types) or not isinstance(limit, int) or not 1 <= limit <= 50:
+        return failed("validation_error", "Provide valid input for this tool. Vault and repository selection are managed by Tracenor.")
+    return await execute_read("v1/context/active", {"space_slugs": space_slugs, "types": types, "limit": limit})
+
+
+@mcp.tool()
+async def search_memories(
+    query: str,
+    space_slugs: list[str] | None = None,
+    types: list[str] | None = None,
+    limit: int | None = None,
+    cursor: str | None = None,
+) -> Any:
+    """Search memories allowed for this local repository context."""
+    if (
+        not isinstance(query, str)
+        or not query.strip()
+        or not valid_space_slugs(space_slugs)
+        or not valid_types(types)
+        or (limit is not None and (not isinstance(limit, int) or not 1 <= limit <= 50))
+        or (cursor is not None and (not isinstance(cursor, str) or not cursor))
+    ):
+        return failed("validation_error", "Provide valid input for this tool. Vault and repository selection are managed by Tracenor.")
+    return await execute_read("v1/memories/search", {"query": query.strip(), "space_slugs": space_slugs, "types": types, "limit": limit, "cursor": cursor})
+
+
+@mcp.tool()
+async def propose_memory(space_slug: str, type: str, title: str, content: str, idempotency_key: str) -> Any:
+    """Propose confirmed, actionable memory for platform-selected review."""
+    return await execute_write("v1/memories/proposals", space_slug, type, title, content, idempotency_key)
+
+
+@mcp.tool()
+async def create_approved_memory(space_slug: str, type: str, title: str, content: str, idempotency_key: str) -> Any:
+    """Create an active memory only when it is already confirmed and authorized."""
+    return await execute_write("v1/memories", space_slug, type, title, content, idempotency_key)
+
+
+async def execute_read(path: str, body: dict[str, Any]) -> dict[str, Any] | CallToolResult:
+    try:
+        config = load_config()
+        body = {key: value for key, value in body.items() if value is not None}
+        body["trusted_context"] = {"repository_detection": await detect_local_git_context()}
+        return successful(await ApiClient(config).request(path, body, False, str(uuid4())))
+    except ConfigError:
+        return failed("invalid_mcp_config", "The Tracenor MCP configuration is invalid.")
+    except ApiError as error:
+        return failed(error.code, read_error_message(error.code), error.request_id)
+    except Exception:
+        return failed("api_error", "The Tracenor request could not be completed.")
+
+
+async def execute_write(path: str, space_slug: str, type: str, title: str, content: str, idempotency_key: str) -> dict[str, Any] | CallToolResult:
+    if not (
+        isinstance(space_slug, str)
+        and valid_space_slugs([space_slug])
+        and type in MEMORY_TYPES
+        and isinstance(title, str)
+        and 3 <= len(title.strip()) <= 120
+        and isinstance(content, str)
+        and 1 <= len(content) <= 2000
+    ):
+        return failed("validation_error", "Provide valid input for this tool. Vault and repository selection are managed by Tracenor.")
+    try:
+        UUID(idempotency_key)
+    except (ValueError, TypeError, AttributeError):
+        return failed("validation_error", "Provide valid input for this tool. Vault and repository selection are managed by Tracenor.")
+    try:
+        config = load_config()
+        body = {
+            "space_slug": space_slug.strip(),
+            "type": type,
+            "title": title.strip(),
+            "content": content,
+            "idempotency_key": idempotency_key,
+            "trusted_context": {"repository_detection": await detect_local_git_context()},
+        }
+        receipt = await ApiClient(config).request(path, body, True, idempotency_key)
+        if not valid_receipt(receipt):
+            return failed("invalid_api_response", "Tracenor did not return a valid write receipt.")
+        return successful(receipt)
+    except ConfigError:
+        return failed("invalid_mcp_config", "The Tracenor MCP configuration is invalid.")
+    except ApiError as error:
+        if error.outcome == "unknown":
+            return failed(error.code, "The write outcome is unknown. Retry only with the same idempotency key.", error.request_id, idempotency_key)
+        return failed(error.code, write_error_message(error.code), error.request_id)
+    except Exception:
+        return failed("api_error", "The write outcome is unknown. Retry only with the same idempotency key.", idempotency_key=idempotency_key)
+
+
+def valid_receipt(receipt: dict[str, Any]) -> bool:
+    try:
+        UUID(str(receipt["memory_id"]))
+        UUID(str(receipt["request_id"]))
+        target = receipt["write_target"]
+        return (
+            receipt["status"] in MEMORY_STATUSES
+            and isinstance(target, dict)
+            and target["routing_source"] in {"repository_match", "api_key_default", "single_global_candidate"}
+            and all(UUID(str(target[key])) for key in ("vault_id", "space_id"))
+        )
+    except (KeyError, TypeError, ValueError):
+        return False
+
+
+def read_error_message(code: str) -> str:
+    return {
+        "context_unavailable": "No memory context is available for this request.",
+        "invalid_api_key": "The configured Tracenor API key is invalid or no longer active.",
+        "request_timeout": "The Tracenor request timed out. You may retry this read.",
+    }.get(code, "The Tracenor request could not be completed.")
+
+
+def write_error_message(code: str) -> str:
+    return {
+        "context_unavailable": "No memory write target is available for this request.",
+        "invalid_api_key": "The configured Tracenor API key is invalid or no longer active.",
+    }.get(code, "The Tracenor write could not be completed.")
+
+
+def main() -> None:
+    try:
+        load_config()
+        mcp.run(transport="stdio")
+    except ConfigError:
+        sys.stderr.write("invalid_mcp_config\n")
+        raise SystemExit(1) from None
+    except Exception:
+        sys.stderr.write("mcp_start_failed\n")
+        raise SystemExit(1) from None