deepy-cli 0.1.13__tar.gz → 0.2.0__tar.gz

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: deepy-cli
-Version: 0.1.13
+Version: 0.2.0
 Summary: Deepy - Vibe coding for DeepSeek models in your terminal
 Keywords: deepseek,coding-agent,terminal,cli,agents
 Author: kirineko
@@ -17,6 +17,7 @@ Requires-Dist: openai>=2.26,<3
 Requires-Dist: orjson>=3.10,<4
 Requires-Dist: pydantic>=2.12,<3
 Requires-Dist: prompt-toolkit>=3.0,<4
+Requires-Dist: pyyaml>=6.0,<7
 Requires-Dist: rich>=13.9,<15
 Requires-Dist: tiktoken>=0.9,<1
 Requires-Dist: tomli-w>=1
@@ -268,6 +269,30 @@ WebSearch uses Deepy's hosted SearXNG endpoint by default. You can override it:
 searxng_url = "https://your-searxng.example/"
 ```
 
+Deepy can also load MCP servers through the OpenAI Agents SDK. Most users only
+need `~/.deepy/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tavily": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "tavily-mcp"],
+      "env": {"TAVILY_API_KEY": "${TAVILY_API_KEY}"},
+      "roles": ["web_search"]
+    }
+  }
+}
+```
+
+When an active MCP tool is marked or detected as web search, Deepy instructs the
+model to prefer it over built-in WebSearch and keeps built-in WebSearch as a
+fallback. Project MCP config is ignored by default because stdio MCP servers can
+start local commands; enable `mcp.allow_project_config` only for trusted
+projects. Use `/mcp` to inspect server status and exposed tools. Advanced MCP
+configuration is documented in [docs/mcp.md](docs/mcp.md).
+
 ## Command Reference
 
 ```bash
@@ -284,15 +309,59 @@ deepy sessions show <session-id>
 deepy run "summarize this project"
 ```
 
-## Project Rules And Skills
+Inside the interactive terminal:
+
+```text
+/skills                 Manage local and market skills
+/skills list            List discovered skills
+/skills search <query>  Search the configured skill market
+/skills install <name>  Install a market skill
+/skill:<name> [request] Invoke a skill directly
+/init                   Create or update project AGENTS.md
+/mcp                    Show MCP server status and tools
+```
+
+## AGENTS.md Instructions And Skills
+
+Deepy automatically loads agent-facing instructions from:
+
+- `~/.deepy/AGENTS.md` for Deepy-wide personal guidance
+- `AGENTS.md` files from the git root down to the current working directory
+- `.agents/skills/*/SKILL.md`
 
-Deepy automatically loads project instructions from:
+Project `AGENTS.md` files are loaded from broad to specific. A file in a nested
+directory appears after the repository root file and takes precedence when rules
+conflict. Direct user instructions still take precedence over loaded
+`AGENTS.md` guidance.
+
+A concise `AGENTS.md` works best:
+
+```markdown
+# AGENTS.md
+
+## Commands
+- Test: `uv run pytest`
+- Lint: `uv run ruff check`
+- Type check: `uv run pyright`
+
+## Architecture
+- Keep CLI entry points thin; put reusable behavior under `src/`.
+
+## Style
+- Prefer small, focused changes that match existing patterns.
+
+## Verification
+- Run focused tests for touched code before broader checks.
+
+## Boundaries
+- Do not rewrite unrelated files or revert user changes.
+```
 
-- `AGENTS.md`
-- `.deepy/skills/*/SKILL.md`
+Skills remain standard Agent Skills under `.agents/skills/*/SKILL.md` and are
+loaded through the skill progressive-disclosure flow.
 
-This lets each repository define local conventions, commands, review rules, and
-domain-specific workflows without changing global config.
+Run `/init` in the interactive terminal to have Deepy inspect the repository and
+create or refresh the project root `AGENTS.md`.
 
 ## Development
 

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/README.md

@@ -240,6 +240,30 @@ WebSearch uses Deepy's hosted SearXNG endpoint by default. You can override it:
 searxng_url = "https://your-searxng.example/"
 ```
 
+Deepy can also load MCP servers through the OpenAI Agents SDK. Most users only
+need `~/.deepy/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tavily": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "tavily-mcp"],
+      "env": {"TAVILY_API_KEY": "${TAVILY_API_KEY}"},
+      "roles": ["web_search"]
+    }
+  }
+}
+```
+
+When an active MCP tool is marked or detected as web search, Deepy instructs the
+model to prefer it over built-in WebSearch and keeps built-in WebSearch as a
+fallback. Project MCP config is ignored by default because stdio MCP servers can
+start local commands; enable `mcp.allow_project_config` only for trusted
+projects. Use `/mcp` to inspect server status and exposed tools. Advanced MCP
+configuration is documented in [docs/mcp.md](docs/mcp.md).
+
 ## Command Reference
 
 ```bash
@@ -256,15 +280,59 @@ deepy sessions show <session-id>
 deepy run "summarize this project"
 ```
 
-## Project Rules And Skills
+Inside the interactive terminal:
+
+```text
+/skills                 Manage local and market skills
+/skills list            List discovered skills
+/skills search <query>  Search the configured skill market
+/skills install <name>  Install a market skill
+/skill:<name> [request] Invoke a skill directly
+/init                   Create or update project AGENTS.md
+/mcp                    Show MCP server status and tools
+```
+
+## AGENTS.md Instructions And Skills
+
+Deepy automatically loads agent-facing instructions from:
+
+- `~/.deepy/AGENTS.md` for Deepy-wide personal guidance
+- `AGENTS.md` files from the git root down to the current working directory
+- `.agents/skills/*/SKILL.md`
 
-Deepy automatically loads project instructions from:
+Project `AGENTS.md` files are loaded from broad to specific. A file in a nested
+directory appears after the repository root file and takes precedence when rules
+conflict. Direct user instructions still take precedence over loaded
+`AGENTS.md` guidance.
+
+A concise `AGENTS.md` works best:
+
+```markdown
+# AGENTS.md
+
+## Commands
+- Test: `uv run pytest`
+- Lint: `uv run ruff check`
+- Type check: `uv run pyright`
+
+## Architecture
+- Keep CLI entry points thin; put reusable behavior under `src/`.
+
+## Style
+- Prefer small, focused changes that match existing patterns.
+
+## Verification
+- Run focused tests for touched code before broader checks.
+
+## Boundaries
+- Do not rewrite unrelated files or revert user changes.
+```
 
-- `AGENTS.md`
-- `.deepy/skills/*/SKILL.md`
+Skills remain standard Agent Skills under `.agents/skills/*/SKILL.md` and are
+loaded through the skill progressive-disclosure flow.
 
-This lets each repository define local conventions, commands, review rules, and
-domain-specific workflows without changing global config.
+Run `/init` in the interactive terminal to have Deepy inspect the repository and
+create or refresh the project root `AGENTS.md`.
 
 ## Development
 

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepy-cli"
-version = "0.1.13"
+version = "0.2.0"
 description = "Deepy - Vibe coding for DeepSeek models in your terminal"
 readme = "README.md"
 authors = [
@@ -23,6 +23,7 @@ dependencies = [
     "orjson>=3.10,<4",
     "pydantic>=2.12,<3",
     "prompt-toolkit>=3.0,<4",
+    "pyyaml>=6.0,<7",
     "rich>=13.9,<15",
     "tiktoken>=0.9,<1",
     "tomli-w>=1",

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/src/deepy/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.1.13"
+__version__ = "0.2.0"
 
 
 def main() -> None:

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/src/deepy/config/__init__.py

@@ -8,6 +8,8 @@ from .settings import (
     DEFAULT_UI_THEME,
     DEFAULT_WEB_SEARCH_SEARXNG_URL,
     DeepSeekModelInfo,
+    McpConfig,
+    McpWebSearchConfig,
     ModelConfig,
     REASONING_MODES,
     Settings,
@@ -16,6 +18,7 @@ from .settings import (
     UI_THEMES,
     UiConfig,
     default_config_path,
+    default_mcp_config_path,
     is_supported_deepseek_model,
     is_valid_ui_theme,
     is_valid_reasoning_mode,
@@ -37,6 +40,8 @@ __all__ = [
     "DEFAULT_UI_THEME",
     "DEFAULT_WEB_SEARCH_SEARXNG_URL",
     "DeepSeekModelInfo",
+    "McpConfig",
+    "McpWebSearchConfig",
     "ModelConfig",
     "REASONING_MODES",
     "Settings",
@@ -45,6 +50,7 @@ __all__ = [
     "UI_THEMES",
     "UiConfig",
     "default_config_path",
+    "default_mcp_config_path",
     "is_supported_deepseek_model",
     "is_valid_ui_theme",
     "is_valid_reasoning_mode",

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/src/deepy/config/settings.py

@@ -16,6 +16,11 @@ DEFAULT_RESERVED_CONTEXT_TOKENS = 50_000
 DEFAULT_COMPACT_PRESERVE_RECENT_MESSAGES = 2
 DEFAULT_WEB_SEARCH_SEARXNG_URL = "https://s.kirineko.tech/"
 DEFAULT_UI_THEME = "auto"
+DEFAULT_MCP_ENABLED = True
+DEFAULT_MCP_CONNECT_TIMEOUT_SECONDS = 10.0
+DEFAULT_MCP_CLEANUP_TIMEOUT_SECONDS = 10.0
+DEFAULT_MCP_CLIENT_SESSION_TIMEOUT_SECONDS = 30.0
+DEFAULT_MCP_CACHE_TOOLS_LIST = True
 REASONING_EFFORTS = {"high", "max"}
 REASONING_MODES = {"none", "high", "max"}
 UI_THEMES = {"auto", "dark", "light"}
@@ -50,6 +55,12 @@ def default_config_path() -> Path:
     return Path.home() / ".deepy" / "config.toml"
 
 
+def default_mcp_config_path(config_path: Path | None = None) -> Path:
+    if config_path is not None:
+        return config_path.expanduser().parent / "mcp.json"
+    return Path.home() / ".deepy" / "mcp.json"
+
+
 def mask_secret(value: str | None) -> str:
     if not value:
         return ""
@@ -212,6 +223,63 @@ class ToolsConfig:
         return cls(web_search=WebSearchToolConfig.from_mapping(_as_mapping(raw.get("web_search"))))
 
 
+@dataclass(frozen=True)
+class McpWebSearchConfig:
+    prefer_mcp: bool = True
+    preferred_server: str | None = None
+    preferred_tools: tuple[str, ...] = ()
+    fallback_to_builtin: bool = True
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> Self:
+        tools = raw.get("preferred_tools")
+        preferred_tools = (
+            tuple(item.strip() for item in tools if isinstance(item, str) and item.strip())
+            if isinstance(tools, list)
+            else ()
+        )
+        return cls(
+            prefer_mcp=_as_bool(raw.get("prefer_mcp"), True),
+            preferred_server=_as_str(raw.get("preferred_server")) or None,
+            preferred_tools=preferred_tools,
+            fallback_to_builtin=_as_bool(raw.get("fallback_to_builtin"), True),
+        )
+
+
+@dataclass(frozen=True)
+class McpConfig:
+    enabled: bool = DEFAULT_MCP_ENABLED
+    connect_timeout_seconds: float = DEFAULT_MCP_CONNECT_TIMEOUT_SECONDS
+    cleanup_timeout_seconds: float = DEFAULT_MCP_CLEANUP_TIMEOUT_SECONDS
+    client_session_timeout_seconds: float = DEFAULT_MCP_CLIENT_SESSION_TIMEOUT_SECONDS
+    cache_tools_list: bool = DEFAULT_MCP_CACHE_TOOLS_LIST
+    allow_project_config: bool = False
+    prefer_mcp_web_search: bool = True
+    web_search: McpWebSearchConfig = field(default_factory=McpWebSearchConfig)
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any]) -> Self:
+        return cls(
+            enabled=_as_bool(raw.get("enabled"), DEFAULT_MCP_ENABLED),
+            connect_timeout_seconds=_as_float(
+                raw.get("connect_timeout_seconds"),
+                DEFAULT_MCP_CONNECT_TIMEOUT_SECONDS,
+            ),
+            cleanup_timeout_seconds=_as_float(
+                raw.get("cleanup_timeout_seconds"),
+                DEFAULT_MCP_CLEANUP_TIMEOUT_SECONDS,
+            ),
+            client_session_timeout_seconds=_as_float(
+                raw.get("client_session_timeout_seconds"),
+                DEFAULT_MCP_CLIENT_SESSION_TIMEOUT_SECONDS,
+            ),
+            cache_tools_list=_as_bool(raw.get("cache_tools_list"), DEFAULT_MCP_CACHE_TOOLS_LIST),
+            allow_project_config=_as_bool(raw.get("allow_project_config"), False),
+            prefer_mcp_web_search=_as_bool(raw.get("prefer_mcp_web_search"), True),
+            web_search=McpWebSearchConfig.from_mapping(_as_mapping(raw.get("web_search"))),
+        )
+
+
 @dataclass(frozen=True)
 class UiConfig:
     theme: str = DEFAULT_UI_THEME
@@ -232,6 +300,7 @@ class Settings:
     logging: LoggingConfig = field(default_factory=LoggingConfig)
     notify: NotifyConfig = field(default_factory=NotifyConfig)
     tools: ToolsConfig = field(default_factory=ToolsConfig)
+    mcp: McpConfig = field(default_factory=McpConfig)
     ui: UiConfig = field(default_factory=UiConfig)
     path: Path | None = None
 
@@ -249,6 +318,7 @@ class Settings:
             logging=LoggingConfig.from_mapping(_as_mapping(raw.get("logging"))),
             notify=NotifyConfig.from_mapping(_as_mapping(raw.get("notify"))),
             tools=ToolsConfig.from_mapping(_as_mapping(raw.get("tools"))),
+            mcp=McpConfig.from_mapping(_as_mapping(raw.get("mcp"))),
             ui=UiConfig.from_mapping(_as_mapping(raw.get("ui"))),
             path=path,
         )
@@ -354,6 +424,21 @@ def write_config(
                 "searxng_url": DEFAULT_WEB_SEARCH_SEARXNG_URL,
             },
         },
+        "mcp": {
+            "enabled": DEFAULT_MCP_ENABLED,
+            "connect_timeout_seconds": DEFAULT_MCP_CONNECT_TIMEOUT_SECONDS,
+            "cleanup_timeout_seconds": DEFAULT_MCP_CLEANUP_TIMEOUT_SECONDS,
+            "client_session_timeout_seconds": DEFAULT_MCP_CLIENT_SESSION_TIMEOUT_SECONDS,
+            "cache_tools_list": DEFAULT_MCP_CACHE_TOOLS_LIST,
+            "allow_project_config": False,
+            "prefer_mcp_web_search": True,
+            "web_search": {
+                "prefer_mcp": True,
+                "preferred_server": "",
+                "preferred_tools": [],
+                "fallback_to_builtin": True,
+            },
+        },
         "ui": {
             "theme": theme,
         },

deepy_cli-0.2.0/src/deepy/data/skills/skill-creator/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: skill-creator
+description: Create or update Agent Skills for Deepy. Use when the user wants to design, write, validate, or improve a reusable skill.
+metadata:
+  short-description: Create or update an Agent Skill
+---
+
+# Skill Creator
+
+Use this skill when creating or improving an Agent Skill.
+
+## Skill Shape
+
+An Agent Skill is a directory with a required `SKILL.md` file:
+
+```text
+skill-name/
+├── SKILL.md
+├── scripts/
+├── references/
+└── assets/
+```
+
+`SKILL.md` uses YAML frontmatter followed by concise Markdown instructions:
+
+```markdown
+---
+name: code-review
+description: Review code changes for correctness, regressions, and missing tests.
+---
+
+# Code Review
+
+Review the change before summarizing it. Lead with findings.
+```
+
+## Rules
+
+- Store user skills in `~/.agents/skills/<name>/SKILL.md`.
+- Store project skills in `<project>/.agents/skills/<name>/SKILL.md`.
+- Use lowercase letters, digits, and hyphens for skill names.
+- Keep `SKILL.md` focused. Move detailed material to `references/`.
+- Use `scripts/` for deterministic repeated operations.
+- Use `assets/` for templates or files that support final outputs.
+- Do not add market-specific metadata to the skill directory.
+
+## Creation Process
+
+1. Identify the concrete situations that should trigger the skill.
+2. Choose a short hyphen-case name.
+3. Write a clear `description` that says when to use the skill.
+4. Keep the main workflow in `SKILL.md`.
+5. Add references, scripts, or assets only when they remove real repetition or ambiguity.
+6. Validate that the skill can be discovered by Deepy with `/skills list`.

deepy_cli-0.2.0/src/deepy/data/skills/skill-installer/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: skill-installer
+description: Install, uninstall, update, and inspect Deepy skills from the configured Deepy skill market.
+metadata:
+  short-description: Install skills from Deepy's market
+---
+
+# Skill Installer
+
+Use this skill when the user wants to browse, install, uninstall, update, or inspect skills.
+
+## Deepy Skill Commands
+
+- `/skills` shows available management commands.
+- `/skills list` lists local project, user, and built-in skills.
+- `/skills search [query]` searches the configured Deepy skill market.
+- `/skills install <name>` installs a market skill into `~/.agents/skills/<name>`.
+- `/skills uninstall <name>` removes a skill installed by Deepy's market installer.
+- `/skills installed` lists market-installed skills.
+- `/skills update <name>` updates one market-installed skill when a newer upload exists.
+- `/skills update --all` updates all market-installed skills when newer uploads exist.
+- `/skill:<name> [request]` actively invokes an installed or built-in skill.
+
+## Storage Rules
+
+- Skill content must stay in standard Agent Skills directories.
+- User-installed skills go under `~/.agents/skills`.
+- Project skills go under `.agents/skills`.
+- Deepy market installation records live under `~/.deepy/skill-market/`.
+- Do not put market lock files inside a skill directory.
+
+## Safety
+
+Before uninstalling or updating a market-installed skill, compare the current skill content hash with Deepy's install record. If the user modified the skill locally, report the modification and do not overwrite or delete it by default.

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/src/deepy/data/tools/WebSearch.md

@@ -10,6 +10,11 @@ SearXNG instances with limiter enabled are less likely to reject the request as
 bot traffic. If SearXNG cannot be reached or returns no parseable results, falls
 back to Deepy's built-in DuckDuckGo HTML search implementation.
 
+If MCP web-search tools are listed in the system prompt, prefer those MCP tools
+first for web/current-information searches. Use this built-in WebSearch as the
+fallback when MCP search is unavailable, fails, or the user explicitly asks for
+Deepy's built-in search.
+
 Keep searches targeted. After several successful searches, stop searching and
 synthesize from the gathered sources. Use `WebFetch` for exact URLs that need
 deeper reading instead of continuing broad search queries.

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/src/deepy/llm/agent.py

@@ -18,14 +18,26 @@ def build_deepy_agent(
     project_root: Path,
     provider: ProviderBundle | None = None,
     loaded_skills: list[SkillInfo] | None = None,
+    mcp_servers: list[object] | None = None,
+    preferred_mcp_web_search_tools: list[str] | None = None,
 ):
     from agents import Agent
 
     provider = provider or build_provider_bundle(settings)
     return Agent(
         name="Deepy",
-        instructions=build_system_prompt(project_root, settings, loaded_skills=loaded_skills),
+        instructions=build_system_prompt(
+            project_root,
+            settings,
+            loaded_skills=loaded_skills,
+            preferred_mcp_web_search_tools=preferred_mcp_web_search_tools,
+        ),
         model=provider.model,
         model_settings=provider.model_settings,
-        tools=build_function_tools(runtime),
+        tools=build_function_tools(
+            runtime,
+            preferred_mcp_web_search_tools=preferred_mcp_web_search_tools,
+        ),
+        mcp_servers=list(mcp_servers or []),
+        mcp_config={"include_server_in_tool_names": True},
     )

{deepy_cli-0.1.13 → deepy_cli-0.2.0}/src/deepy/llm/events.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Literal
 
+from deepy.utils import json as json_utils
+
 StreamKind = Literal[
     "text_delta",
     "reasoning_delta",
@@ -84,7 +86,7 @@ def normalize_stream_event(event: Any) -> DeepyStreamEvent | None:
         return DeepyStreamEvent(
             kind="tool_output",
             name=_tool_name(item),
-            text=output if isinstance(output, str) else str(output),
+            text=_tool_output_text(output),
             payload={"call_id": _call_id(item)},
         )
     if name == "message_output_created":
@@ -159,6 +161,14 @@ def _tool_arguments(item: Any) -> str:
     return value if isinstance(value, str) else ""
 
 
+def _tool_output_text(output: Any) -> str:
+    if isinstance(output, str):
+        return output
+    if output is None:
+        return ""
+    return json_utils.dumps(output)
+
+
 def _call_id(item: Any) -> str:
     if item is None:
         return ""