devtime-ei 0.1.1__tar.gz → 0.1.2__tar.gz

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devtime-ei
-Version: 0.1.1
+Version: 0.1.2
 Summary: Local-first Engineering Intelligence for software repositories
 Author-email: Aviad Shakargi <aviad94@gmail.com>
 Maintainer-email: Aviad Shakargi <aviad94@gmail.com>
@@ -8,7 +8,7 @@ License: Apache-2.0
 Project-URL: Homepage, https://github.com/Shakargy/devtime
 Project-URL: Repository, https://github.com/Shakargy/devtime
 Project-URL: Issues, https://github.com/Shakargy/devtime/issues
-Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.1
+Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.2
 Project-URL: Demo, https://youtu.be/1Hiu3Y9J_SI
 Keywords: devtools,cli,static-analysis,repository-analysis,engineering-intelligence,local-first
 Classifier: Development Status :: 3 - Alpha
@@ -30,8 +30,11 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pathspec>=0.12
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mcp>=1.2; extra == "dev"
 Dynamic: license-file
 
 # DevTime
@@ -46,11 +49,11 @@ risky changes.
 
 > No cloud. No telemetry. No code execution. No AI required.
 
-[![DevTime demo - Repository memory from evidence](assets/devtime-demo-thumbnail-v0.1.0.png)](https://youtu.be/1Hiu3Y9J_SI)
+![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
 
-Watch the 2-minute demo: DevTime scans a repo locally, explains concepts from
-evidence, surfaces uncertainty, catches a risky diff, and shows how a corroborated
-decision improves understanding.
+Prefer video? [Watch the 2-minute demo](https://youtu.be/1Hiu3Y9J_SI): DevTime scans
+a repo locally, explains concepts from evidence, surfaces uncertainty, catches a
+risky diff, and shows how a corroborated decision improves understanding.
 
 ---
 
@@ -203,11 +206,55 @@ Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATI
 | `dtc decision add` | Add a local decision record that can reduce uncertainty. |
 
 (Also available: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`,
-`dtc export`, `dtc reset`.)
+`dtc export`, `dtc reset`, `dtc mcp start`.)
 
 Requires **Python >= 3.11** and git. See **[QUICKSTART.md](QUICKSTART.md)** for a
 step-by-step first run and troubleshooting.
 
+## Use with coding agents (MCP)
+
+Your coding agent starts every session amnesiac about your repository and then
+guesses, confidently. DevTime gives it memory it can trust: a local, read-only MCP
+server that answers only with claims the repository can prove, plus explicit
+uncertainty for what it cannot.
+
+Install with MCP support and scan your repo:
+
+```bash
+pipx install "devtime-ei[mcp]"
+cd your-repo
+dtc init
+dtc scan
+```
+
+Add DevTime to Claude Code:
+
+```bash
+claude mcp add devtime -- dtc mcp start
+```
+
+Or in any MCP client that reads `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "devtime": {
+      "command": "dtc",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+The agent gets three read-only tools: `list_concepts`, `explain_concept`, and
+`get_context_pack` (governed context with do-not-change-without-review paths, tests
+to run, and agent guidance). Local stdio only - no network listener, no write tools,
+no source code returned, only evidence file paths.
+
+DevTime is listed in the official MCP Registry as `io.github.shakargy/devtime`.
+
+<!-- mcp-name: io.github.shakargy/devtime -->
+
 ## Installation
 
 Recommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`
@@ -310,7 +357,7 @@ intentionally not built yet - in **[LIMITATIONS.md](LIMITATIONS.md)**.
 ## Roadmap
 
 This is an early, local-first V0 focused on being trustworthy before being large.
-Not yet built (intentionally): git-history signals, wired MCP transport, an AI
+Not yet built (intentionally): git-history signals, write-enabled MCP tools, an AI
 provider, a UI, and any cloud/team/enterprise features. See **[ROADMAP.md](ROADMAP.md)**.
 
 ## Contributing

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/README.md

@@ -10,11 +10,11 @@ risky changes.
 
 > No cloud. No telemetry. No code execution. No AI required.
 
-[![DevTime demo - Repository memory from evidence](assets/devtime-demo-thumbnail-v0.1.0.png)](https://youtu.be/1Hiu3Y9J_SI)
+![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
 
-Watch the 2-minute demo: DevTime scans a repo locally, explains concepts from
-evidence, surfaces uncertainty, catches a risky diff, and shows how a corroborated
-decision improves understanding.
+Prefer video? [Watch the 2-minute demo](https://youtu.be/1Hiu3Y9J_SI): DevTime scans
+a repo locally, explains concepts from evidence, surfaces uncertainty, catches a
+risky diff, and shows how a corroborated decision improves understanding.
 
 ---
 
@@ -167,11 +167,55 @@ Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATI
 | `dtc decision add` | Add a local decision record that can reduce uncertainty. |
 
 (Also available: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`,
-`dtc export`, `dtc reset`.)
+`dtc export`, `dtc reset`, `dtc mcp start`.)
 
 Requires **Python >= 3.11** and git. See **[QUICKSTART.md](QUICKSTART.md)** for a
 step-by-step first run and troubleshooting.
 
+## Use with coding agents (MCP)
+
+Your coding agent starts every session amnesiac about your repository and then
+guesses, confidently. DevTime gives it memory it can trust: a local, read-only MCP
+server that answers only with claims the repository can prove, plus explicit
+uncertainty for what it cannot.
+
+Install with MCP support and scan your repo:
+
+```bash
+pipx install "devtime-ei[mcp]"
+cd your-repo
+dtc init
+dtc scan
+```
+
+Add DevTime to Claude Code:
+
+```bash
+claude mcp add devtime -- dtc mcp start
+```
+
+Or in any MCP client that reads `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "devtime": {
+      "command": "dtc",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+The agent gets three read-only tools: `list_concepts`, `explain_concept`, and
+`get_context_pack` (governed context with do-not-change-without-review paths, tests
+to run, and agent guidance). Local stdio only - no network listener, no write tools,
+no source code returned, only evidence file paths.
+
+DevTime is listed in the official MCP Registry as `io.github.shakargy/devtime`.
+
+<!-- mcp-name: io.github.shakargy/devtime -->
+
 ## Installation
 
 Recommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`
@@ -274,7 +318,7 @@ intentionally not built yet - in **[LIMITATIONS.md](LIMITATIONS.md)**.
 ## Roadmap
 
 This is an early, local-first V0 focused on being trustworthy before being large.
-Not yet built (intentionally): git-history signals, wired MCP transport, an AI
+Not yet built (intentionally): git-history signals, write-enabled MCP tools, an AI
 provider, a UI, and any cloud/team/enterprise features. See **[ROADMAP.md](ROADMAP.md)**.
 
 ## Contributing

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devtime-ei"
-version = "0.1.1"
+version = "0.1.2"
 description = "Local-first Engineering Intelligence for software repositories"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -37,15 +37,20 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Read-only MCP stdio server for coding agents (dtc mcp start).
+mcp = [
+    "mcp>=1.2",
+]
 dev = [
     "pytest>=8.0",
+    "mcp>=1.2",
 ]
 
 [project.urls]
 Homepage = "https://github.com/Shakargy/devtime"
 Repository = "https://github.com/Shakargy/devtime"
 Issues = "https://github.com/Shakargy/devtime/issues"
-"Release Notes" = "https://github.com/Shakargy/devtime/releases/tag/v0.1.1"
+"Release Notes" = "https://github.com/Shakargy/devtime/releases/tag/v0.1.2"
 Demo = "https://youtu.be/1Hiu3Y9J_SI"
 
 [project.scripts]

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/src/devtime/__init__.py

@@ -1,6 +1,6 @@
 """DevTime - local-first Engineering Intelligence for repository memory."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 # Version metadata (Builder Edition, Chapter 20).
 EVIDENCE_MODEL = "2026.06.1"

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/src/devtime/cli.py

@@ -341,20 +341,33 @@ def decision_add(
 
 @mcp_app.command("start")
 def mcp_start() -> None:
-    """Preview planned read-only MCP tools. Does NOT start a server in V0."""
-    from devtime.mcp.server import describe_server
+    """Start the local read-only MCP server over stdio (for coding agents)."""
+    # stdout belongs to the JSON-RPC stream: all diagnostics go to stderr.
+    err = Console(stderr=True)
+
+    if not paths.is_initialized():
+        err.print("[red]DevTime is not initialized here.[/red]")
+        err.print("Run [bold]dtc init[/bold] and [bold]dtc scan[/bold] in the repository first.")
+        raise typer.Exit(code=2)
 
-    console.print(describe_server())
-    # Honest exit: nothing was started, so a command named "start" returns nonzero.
-    raise typer.Exit(code=1)
+    from devtime.mcp.transport import McpDependencyMissing, run_stdio
+
+    err.print("DevTime MCP server: stdio, read-only, local only. Ctrl+C to stop.")
+    try:
+        run_stdio()
+    except McpDependencyMissing as exc:
+        # markup=False: the hint contains [mcp], which rich would eat as a tag.
+        err.print(str(exc), markup=False, style="red")
+        raise typer.Exit(code=1)
 
 
 @mcp_app.command("preview")
 def mcp_preview() -> None:
-    """Preview planned read-only MCP tools (transport not implemented in V0)."""
+    """Show implemented and planned read-only MCP tools."""
     from devtime.mcp.server import describe_server
 
-    console.print(describe_server())
+    # markup=False: the text contains [mcp], which rich would eat as a tag.
+    console.print(describe_server(), markup=False)
 
 
 @mcp_app.command("status")

devtime_ei-0.1.2/src/devtime/mcp/server.py

@@ -0,0 +1,42 @@
+"""MCP server description (Builder Edition, Chapter 16).
+
+v0.1.2: the stdio transport is implemented for the read-only tool subset in
+devtime.mcp.transport. The remaining planned tools stay listed as planned so
+the preview output never overclaims.
+"""
+
+from __future__ import annotations
+
+import json
+
+from devtime.mcp import schemas
+from devtime.mcp.transport import IMPLEMENTED_TOOLS
+
+
+def describe_server() -> str:
+    """Honest preview: implemented tools are separated from planned ones."""
+    planned_read = [t for t in schemas.TOOLS["read"] if t not in IMPLEMENTED_TOOLS]
+    planned_context = [t for t in schemas.TOOLS["context"] if t not in IMPLEMENTED_TOOLS]
+    lines = [
+        "MCP transport: stdio, read-only, local only.",
+        'Requires the optional dependency: pip install "devtime-ei[mcp]"',
+        "Start with: dtc mcp start (stdout is the protocol stream).",
+        "",
+        "Implemented tools:",
+    ]
+    lines += [f"  - {t}" for t in IMPLEMENTED_TOOLS]
+    lines += ["Planned read tools (not implemented yet):"]
+    lines += [f"  - {t}" for t in planned_read]
+    lines += ["Planned context tools (not implemented yet):"]
+    lines += [f"  - {t}" for t in planned_context]
+    lines += ["Planned review tools (not implemented yet):"]
+    lines += [f"  - {t}" for t in schemas.TOOLS["review"]]
+    lines += [
+        "",
+        "Write tools are not exposed. No network listener. No source code is returned.",
+    ]
+    return "\n".join(lines)
+
+
+def describe_permissions() -> str:
+    return json.dumps(schemas.DEFAULT_PERMISSIONS, indent=2)

devtime_ei-0.1.2/src/devtime/mcp/transport.py

@@ -0,0 +1,99 @@
+"""Read-only MCP stdio transport (v0.1.2).
+
+Wires the three implemented read tools to a real MCP server over stdio so
+coding agents (Claude Code, Cursor, and other MCP clients) can query local
+DevTime memory.
+
+Trust model, unchanged:
+  - read-only: no write tools are exposed
+  - local only: stdio transport, no network listener
+  - no source code is returned, only claims, evidence paths, and uncertainty
+  - requires the optional dependency: pip install "devtime-ei[mcp]"
+
+IMPORTANT: stdout belongs to the JSON-RPC stream. Nothing here may print to
+stdout; diagnostics go to stderr.
+"""
+
+from __future__ import annotations
+
+from devtime import paths
+from devtime.mcp import tools
+
+SERVER_NAME = "devtime"
+
+SERVER_INSTRUCTIONS = (
+    "DevTime is local, evidence-backed repository memory. "
+    "Every claim links to evidence files; weak evidence is reported as "
+    "uncertainty, not confidence. Use list_concepts to discover what the "
+    "scanned repository supports, explain_concept for claims and evidence "
+    "behind one concept, and get_context_pack for a governed context bundle "
+    "before changing code related to a concept. If results are empty, the "
+    "repository has not been scanned: run `dtc init` and `dtc scan` there first."
+)
+
+# The subset of the planned tool surface that is implemented and exposed.
+IMPLEMENTED_TOOLS = ("list_concepts", "explain_concept", "get_context_pack")
+
+_NOT_INITIALIZED = {
+    "error": "not_initialized",
+    "hint": "No .devtime memory found in the current directory. "
+    "Run `dtc init` then `dtc scan` in the repository first.",
+}
+
+
+class McpDependencyMissing(RuntimeError):
+    """Raised when the optional MCP SDK is not installed."""
+
+    INSTALL_HINT = 'MCP support needs the optional dependency: pip install "devtime-ei[mcp]"'
+
+
+def build_server():
+    """Build the FastMCP server with the read-only tool surface registered."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:  # pragma: no cover - exercised via CLI test
+        raise McpDependencyMissing(McpDependencyMissing.INSTALL_HINT) from exc
+
+    server = FastMCP(SERVER_NAME, instructions=SERVER_INSTRUCTIONS)
+
+    @server.tool()
+    def list_concepts(limit: int = 50) -> list[dict] | dict:
+        """List concepts detected in the scanned repository with confidence labels.
+
+        Start here to discover what the repository memory contains. Returns
+        concept names, slugs, and confidence labels. No source code.
+        """
+        if not paths.is_initialized():
+            return _NOT_INITIALIZED
+        return tools.list_concepts(limit=limit)
+
+    @server.tool()
+    def explain_concept(concept: str) -> dict:
+        """Explain one concept from evidence: claims, evidence file paths, uncertainty, and Understanding Score.
+
+        Claims are evidence-linked; uncertainty lists what the repository
+        cannot prove yet. human_review_required is true when uncertainty
+        exists. No source code is returned, only file paths.
+        """
+        if not paths.is_initialized():
+            return _NOT_INITIALIZED
+        return tools.explain_concept(concept)
+
+    @server.tool()
+    def get_context_pack(concept: str, mode: str = "risk") -> dict:
+        """Get a governed context pack for a concept before changing related code.
+
+        Includes supported claims, corroborated decisions, uncertainty,
+        do-not-change-without-review paths, tests to run, and agent guidance.
+        Modes: risk (default), onboarding.
+        """
+        if not paths.is_initialized():
+            return _NOT_INITIALIZED
+        return tools.get_context_pack(concept, mode=mode)
+
+    return server
+
+
+def run_stdio() -> None:
+    """Run the read-only MCP server over stdio (blocks until the client disconnects)."""
+    build_server().run()

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/src/devtime_ei.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devtime-ei
-Version: 0.1.1
+Version: 0.1.2
 Summary: Local-first Engineering Intelligence for software repositories
 Author-email: Aviad Shakargi <aviad94@gmail.com>
 Maintainer-email: Aviad Shakargi <aviad94@gmail.com>
@@ -8,7 +8,7 @@ License: Apache-2.0
 Project-URL: Homepage, https://github.com/Shakargy/devtime
 Project-URL: Repository, https://github.com/Shakargy/devtime
 Project-URL: Issues, https://github.com/Shakargy/devtime/issues
-Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.1
+Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.2
 Project-URL: Demo, https://youtu.be/1Hiu3Y9J_SI
 Keywords: devtools,cli,static-analysis,repository-analysis,engineering-intelligence,local-first
 Classifier: Development Status :: 3 - Alpha
@@ -30,8 +30,11 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pathspec>=0.12
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mcp>=1.2; extra == "dev"
 Dynamic: license-file
 
 # DevTime
@@ -46,11 +49,11 @@ risky changes.
 
 > No cloud. No telemetry. No code execution. No AI required.
 
-[![DevTime demo - Repository memory from evidence](assets/devtime-demo-thumbnail-v0.1.0.png)](https://youtu.be/1Hiu3Y9J_SI)
+![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
 
-Watch the 2-minute demo: DevTime scans a repo locally, explains concepts from
-evidence, surfaces uncertainty, catches a risky diff, and shows how a corroborated
-decision improves understanding.
+Prefer video? [Watch the 2-minute demo](https://youtu.be/1Hiu3Y9J_SI): DevTime scans
+a repo locally, explains concepts from evidence, surfaces uncertainty, catches a
+risky diff, and shows how a corroborated decision improves understanding.
 
 ---
 
@@ -203,11 +206,55 @@ Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATI
 | `dtc decision add` | Add a local decision record that can reduce uncertainty. |
 
 (Also available: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`,
-`dtc export`, `dtc reset`.)
+`dtc export`, `dtc reset`, `dtc mcp start`.)
 
 Requires **Python >= 3.11** and git. See **[QUICKSTART.md](QUICKSTART.md)** for a
 step-by-step first run and troubleshooting.
 
+## Use with coding agents (MCP)
+
+Your coding agent starts every session amnesiac about your repository and then
+guesses, confidently. DevTime gives it memory it can trust: a local, read-only MCP
+server that answers only with claims the repository can prove, plus explicit
+uncertainty for what it cannot.
+
+Install with MCP support and scan your repo:
+
+```bash
+pipx install "devtime-ei[mcp]"
+cd your-repo
+dtc init
+dtc scan
+```
+
+Add DevTime to Claude Code:
+
+```bash
+claude mcp add devtime -- dtc mcp start
+```
+
+Or in any MCP client that reads `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "devtime": {
+      "command": "dtc",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+The agent gets three read-only tools: `list_concepts`, `explain_concept`, and
+`get_context_pack` (governed context with do-not-change-without-review paths, tests
+to run, and agent guidance). Local stdio only - no network listener, no write tools,
+no source code returned, only evidence file paths.
+
+DevTime is listed in the official MCP Registry as `io.github.shakargy/devtime`.
+
+<!-- mcp-name: io.github.shakargy/devtime -->
+
 ## Installation
 
 Recommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`
@@ -310,7 +357,7 @@ intentionally not built yet - in **[LIMITATIONS.md](LIMITATIONS.md)**.
 ## Roadmap
 
 This is an early, local-first V0 focused on being trustworthy before being large.
-Not yet built (intentionally): git-history signals, wired MCP transport, an AI
+Not yet built (intentionally): git-history signals, write-enabled MCP tools, an AI
 provider, a UI, and any cloud/team/enterprise features. See **[ROADMAP.md](ROADMAP.md)**.
 
 ## Contributing

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/src/devtime_ei.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ src/devtime/mcp/__init__.py
 src/devtime/mcp/schemas.py
 src/devtime/mcp/server.py
 src/devtime/mcp/tools.py
+src/devtime/mcp/transport.py
 src/devtime/output/__init__.py
 src/devtime/output/json_export.py
 src/devtime/output/markdown.py

{devtime_ei-0.1.1 → devtime_ei-0.1.2}/src/devtime_ei.egg-info/requires.txt

@@ -7,3 +7,7 @@ pathspec>=0.12
 
 [dev]
 pytest>=8.0
+mcp>=1.2
+
+[mcp]
+mcp>=1.2

devtime_ei-0.1.1/src/devtime/mcp/server.py

@@ -1,35 +0,0 @@
-"""MCP server description (Builder Edition, Chapter 16).
-
-V0 ships the tool surface, schemas, and permission model. The actual transport
-(stdio/socket via an MCP SDK) is wired in a later milestone; this module makes
-the read-only contract inspectable today.
-"""
-
-from __future__ import annotations
-
-import json
-
-from devtime.intelligence.context_pack import generate_context_pack  # noqa: F401
-from devtime.mcp import schemas
-
-
-def describe_server() -> str:
-    """Honest preview output (Trust Repair v0.0.6): no server is started, and no
-    bind address is shown, because the MCP transport is not implemented in V0."""
-    lines = [
-        "MCP transport is not implemented in V0.",
-        "No server was started.",
-        "This command is a preview of planned read-only MCP tools.",
-        "",
-        "Planned read tools:",
-    ]
-    lines += [f"  - {t}" for t in schemas.TOOLS["read"]]
-    lines += ["Planned context tools:"]
-    lines += [f"  - {t}" for t in schemas.TOOLS["context"]]
-    lines += ["Planned review tools:"]
-    lines += [f"  - {t}" for t in schemas.TOOLS["review"]]
-    return "\n".join(lines)
-
-
-def describe_permissions() -> str:
-    return json.dumps(schemas.DEFAULT_PERMISSIONS, indent=2)