agent-godmode

io.github.mdvohra由 GitHub 帳號 mdvohra 發布v0.1.9更新於 Oct 24, 2026

Sandboxed workspace MCP: file ops, argv-only run_command, list_files; BYO LLM prompts.

已驗證STDIO僅桌面檔案與儲存開發者工具

概覽

AI 產生的概覽

沙箱式工作區 MCP 伺服器,讓助理在單一根目錄內讀寫編輯檔案、列出目錄,並以 argv 方式執行指令。

可以做什麼
  • 讀取 UTF-8 文字檔,可指定行範圍與位元組上限
  • 建立、覆寫或附加文字檔,並自動建立上層目錄
  • 在既有檔案中做尋找取代,預設要求精確符合一次,也可全部取代
  • 列出目錄項目,支援遞迴、glob、深度限制與隱藏檔案開關
  • 僅以 argv 清單方式執行子程序,可指定根目錄內的工作目錄
適用情境
適合讓助理在本地程式碼或文件專案中工作,同時被限制在一個目錄內,例如 Cursor 風格的編輯以及執行建置或測試指令。它也附帶具版本號的系統提示詞與 OpenAI 風格工具定義,方便在 Python 中接上自己的 LLM 迴圈。
執行需求
以 stdio 本地程序執行,從 PyPI 安裝(pip install agent-godmode)。需要絕對路徑的工作區根目錄,透過環境變數 AGENT_GODMODE_ROOT 或命令列參數 --root 傳入。選用變數可調整讀取大小、指令逾時、輸出截斷、列目錄上限與允許的指令清單。伺服器本身不需要 API 金鑰;README 中的 OpenAI 範例需在你自己的應用程式設定 OPENAI_API_KEY。
安裝前請注意
助理可在根目錄內寫入、覆寫、編輯檔案並執行任意子程序;若未設定 AGENT_GODMODE_ALLOWED_COMMANDS,所有指令都會被允許。子程序會繼承目前環境變數,伺服器可見的密鑰可能被子程序讀取。路徑雖被限制在根目錄內,仍應指向你可控的目錄,並備份重要檔案。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 agent-godmode,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

agent-godmode

Workspace-scoped MCP tools for building Cursor-style agents: read_file, write_file, edit_file, run_command, list_files. Includes strict, versioned system prompts (SYSTEM_PROMPT_V1) and OpenAI-style tool definitions so your app can wire any LLM with one import.

The LLM and API keys stay in your app. This package provides tool execution, sandboxing, and prompts—not a hosted model.

OpenAI + in-process tools: the Tier B section below is self-contained—copy the Python into a script, module, or REPL; no separate artifact is required.

Install

bash
pip install agent-godmode

Editable / dev:

bash
pip install -e ".[dev]"

Migrating from mcp-agent-tools: uninstall the old package, install agent-godmode, change Python imports from mcp_agent_tools to agent_godmode, the CLI from mcp-agent-tools to agent-godmode, and environment variables from MCP_AGENT_TOOLS_* to AGENT_GODMODE_* (for example AGENT_GODMODE_ROOT).

Tools

All tools are scoped to a single workspace root. Paths are relative to that root (or absolute only if they resolve under it). The same operations are available over MCP (the agent-godmode server) and in-process via AgentWorkspace / WorkspaceTools.

ToolPurpose
read_fileRead a UTF-8 text file; optional line range and byte cap.
write_fileCreate or overwrite/append UTF-8 text; creates parent directories.
edit_fileSearch-and-replace in an existing UTF-8 file: non-empty old_string, optional replace_all. With replace_all=false, old_string must match exactly once (use surrounding context from read_file for uniqueness). Invalid UTF-8 returns an error instead of corrupting binary data.
list_filesList directory entries with optional recursion, glob, depth cap, dotfile control.
run_commandRun a subprocess from an argv list only (no shell); optional cwd under the root.

For LLM integrations, tool shapes and descriptions are centralized in OPENAI_TOOL_DEFINITIONS and TOOL_DESCRIPTIONS; agent behavior is guided by SYSTEM_PROMPT_V1.

Tier A — Cursor (or any MCP client)

1. Pick a workspace directory (only paths under this root are allowed).

2. Add a server entry (stdio). Example for a global MCP config (paths use forward slashes on Windows):

json
{  "mcpServers": {    "agent-godmode": {      "command": "agent-godmode",      "args": [],      "env": {        "AGENT_GODMODE_ROOT": "D:/your/project"      }    }  }}

Or with an explicit CLI root (overrides env for that process):

json
{  "mcpServers": {    "agent-godmode": {      "command": "agent-godmode",      "args": ["--root", "D:/your/project"]    }  }}

3. Paste SYSTEM_PROMPT_V1 (from agent_godmode.prompts or below) into your host’s system prompt if the client does not load server instructions automatically.

Environment variables

VariableMeaning
AGENT_GODMODE_ROOTRequired unless --root is passed. Absolute workspace root.
AGENT_GODMODE_MAX_READ_BYTESMax bytes per read (default 512000).
AGENT_GODMODE_COMMAND_TIMEOUTSubprocess timeout in seconds (default 120).
AGENT_GODMODE_MAX_COMMAND_OUTPUT_BYTESTruncate stdout/stderr combined (default 256000).
AGENT_GODMODE_LIST_MAX_ENTRIESCap for list_files (default 2000).
AGENT_GODMODE_ALLOWED_COMMANDSComma-separated basenames allowed as argv[0] (e.g. python,uv,node). If unset, all commands allowed under the sandbox.

Tier B — Python app (in-process + OpenAI)

Design notes

  • Workspace root — Examples use D:\Avi-assign as a placeholder; point WORK_DIR at any directory you control.
  • API key policy — OPENAI_API_KEY is required only for Chat Completions. Imports set client = OpenAI() if HAS_OPENAI_KEY else None; workspace setup and direct edit_file run without a key.
  • Model-authored I/O — For write_file, persist only text returned by the model. For edit_file, the model must copy old_string exactly from read_file (see SYSTEM_PROMPT_V1).

1. Install dependencies

In a shell or any interactive Python session:

bash
pip install -q openaipip install -q -e "D:/MCP"   # editable checkout; or: pip install agent-godmode

If your environment supports line magics (for example %pip in IPython), you can run the same installs there; do not place shell comments on the same line as %pip.

2. Imports and API key handling

python
import osfrom pathlib import Path
# OPENAI_API_KEY is required only for steps that call Chat Completions (LLM + agent loops).# Workspace + direct edit_file work without a key.# Set via OS env or e.g. %env OPENAI_API_KEY sk-... in IPython# Local-only optional override — never commit a real key:# os.environ["OPENAI_API_KEY"] = "sk-..."
from openai import OpenAI
from agent_godmode import (    AgentWorkspace,    OPENAI_TOOL_DEFINITIONS,    SYSTEM_PROMPT_V1,    run_agent_loop,)
HAS_OPENAI_KEY = bool(os.environ.get("OPENAI_API_KEY"))client = OpenAI() if HAS_OPENAI_KEY else NoneMODEL = "gpt-4o-mini"
if not HAS_OPENAI_KEY:    print(        "Note: OPENAI_API_KEY not set — Chat Completions examples will raise until you set it. "        "Workspace + direct edit_file still work."    )

3. Workspace bootstrap and seed file

python
# Fixed workspace — all reads/writes/commands stay under this folderWORK_DIR = Path(r"D:\Avi-assign")WORK_DIR.mkdir(parents=True, exist_ok=True)print("Workspace:", WORK_DIR.resolve())
hello = WORK_DIR / "hello.txt"if not hello.exists():    hello.write_text("Hello from Avi-assign workspace.\n", encoding="utf-8")
ws = AgentWorkspace(WORK_DIR)print(ws.read_file("hello.txt"))print("--- list_files ---")print(ws.list_files(".", recursive=False))

4. LLM-authored file body (no tool calls)

Requires OPENAI_API_KEY. Skip if you are only exercising tools without the API.

python
if client is None:    raise ValueError(        "Set OPENAI_API_KEY to run this block (e.g. export OPENAI_API_KEY=... or %env in IPython). "        "Skip if you only want workspace / edit_file demos."    )
# 1) Context from disk (read-only)context = ws.read_file("hello.txt")
# 2) Ask the model to author the entire new file; no static template for the bodyuser_prompt = (    "Here is the current contents of hello.txt in my workspace:\n\n"    f"---\n{context}\n---\n\n"    "Write ONLY the body of a new Markdown file (no preamble, no code fences) "    "with a title line and two bullet points explaining what this greeting is for.")
resp = client.chat.completions.create(    model=MODEL,    messages=[        {            "role": "system",            "content": "You output only the file body the user asked for. No extra commentary.",        },        {"role": "user", "content": user_prompt},    ],)
generated = (resp.choices[0].message.content or "").strip()if not generated:    raise RuntimeError("LLM returned empty content; nothing to write.")
# 3) Persist exactly what the LLM producedout_rel = "llm_generated_notes.md"ws.write_file(out_rel, generated, mode="overwrite")print(f"Wrote {out_rel!r} ({len(generated)} chars from model)\n")print(ws.read_file(out_rel))

5. Direct edit_file (no Chat Completions)

No API key required. The next lines create ws if you have not run the workspace section yet (same root).

python
# Direct edit_file (no Chat Completions call).# If `ws` is not defined yet (e.g. you skipped §3), the next few lines create it (same WORK_DIR).from pathlib import Path
from agent_godmode import AgentWorkspace
if "ws" not in globals():    WORK_DIR = Path(r"D:\Avi-assign")    WORK_DIR.mkdir(parents=True, exist_ok=True)    ws = AgentWorkspace(WORK_DIR)
demo_edit = "edit_demo.txt"ws.write_file(    demo_edit,    "version: 1\nstatus: draft\nfooter: end\n",    mode="overwrite",)print("--- before ---")print(ws.read_file(demo_edit), end="")print(ws.edit_file(demo_edit, old_string="status: draft", new_string="status: ready"))print("--- after ---")print(ws.read_file(demo_edit), end="")

6. Agent loop: model calls write_file

Requires OPENAI_API_KEY.

python
if client is None:    raise ValueError(        "Set OPENAI_API_KEY to run this block. "        "Skip if you only need workspace or direct edit_file."    )

def complete(messages, tools):    """One Chat Completions turn; return OpenAI-shaped dict for run_agent_loop."""    resp = client.chat.completions.create(        model=MODEL,        messages=messages,        tools=tools,        tool_choice="auto",    )    return resp.model_dump()

answer = run_agent_loop(    complete,    "Use tools only. List the workspace root, read hello.txt, then call write_file on "    "agent_notes.txt. The `content` argument must be your own freshly written summary "    "(several sentences) based only on what you read—do not paste boilerplate.",    ws,    system_prompt=SYSTEM_PROMPT_V1,    max_turns=12,)print("--- final answer ---")print(answer)print("--- agent_notes.txt (if created by tool write_file) ---")p = WORK_DIR / "agent_notes.txt"print(p.read_text(encoding="utf-8") if p.exists() else "(missing)")

7. Agent loop: model calls edit_file

Requires OPENAI_API_KEY and the complete function from §6.

python
from pathlib import Path
from agent_godmode import AgentWorkspace
if "ws" not in globals():    WORK_DIR = Path(r"D:\Avi-assign")    WORK_DIR.mkdir(parents=True, exist_ok=True)    ws = AgentWorkspace(WORK_DIR)if "complete" not in globals():    raise NameError("Define `complete` in §6 (after imports) before running this block.")if client is None:    raise ValueError(        "Set OPENAI_API_KEY to run this block. "        "The direct edit_file example in §5 works without a key."    )
target = "edit_agent_target.txt"ws.write_file(    target,    "# Demo\nThere are three erorrs in this sentance.\n",    mode="overwrite",)edit_answer = run_agent_loop(    complete,    (        f"Use tools only. Read `{target}`. Then use edit_file (not write_file) to fix typos: "        "change erorrs to errors and sentance to sentence. "        "Copy old_string exactly from read_file; use two edit_file calls or replace_all where appropriate."    ),    ws,    system_prompt=SYSTEM_PROMPT_V1,    max_turns=14,)print("--- agent (edit_file) answer ---")print(edit_answer)print("--- file after agent ---")print(ws.read_file(target), end="")

8. Optional: custom tool loop without run_agent_loop

Use OPENAI_TOOL_DEFINITIONS, call the Chat Completions API with tools=..., parse tool_calls, and route each call through ws.dispatch(name, json.loads(arguments)) (requires import json). For write_file, the content field should be whatever the model authored; for edit_file, pass old_string, new_string, and replace_all exactly as the model returned.

Optional limits on AgentWorkspace

python
ws = AgentWorkspace(    r"D:\Avi-assign",    allowed_commands=frozenset({"python", "uv"}),    command_timeout_sec=60.0,)

Lower-level (WorkspaceTools + OPENAI_TOOL_DEFINITIONS)

Same sandbox without AgentWorkspace: use config_from_root(...) and WorkspaceTools. Pass OPENAI_TOOL_DEFINITIONS to your provider as tools= when you implement your own loop instead of run_agent_loop.

python
from agent_godmode import WorkspaceTools, OPENAI_TOOL_DEFINITIONS, SYSTEM_PROMPT_V1from agent_godmode.config import config_from_root
tools = WorkspaceTools(config_from_root(r"D:\Avi-assign"))print(tools.read_file("hello.txt"))

Compose the system message:

python
final_system = SYSTEM_PROMPT_V1 + "\n\n" + "Your org rules here."

Imports reference

  • AgentWorkspace — pass a directory path; use read_file / write_file / edit_file / list_files / run_command on that tree only
  • SYSTEM_PROMPT_V1, SYSTEM_PROMPT_CHANGELOG, TOOL_DESCRIPTIONS
  • OPENAI_TOOL_DEFINITIONS — same shapes as MCP tools (for tools= in chat completions)
  • build_server(config) — build a FastMCP app (stdio via build_server(cfg).run())
  • run_agent_loop — minimal multi-turn executor with your complete callable (accepts WorkspaceConfig or AgentWorkspace)

Safety model

  • Python: all paths are resolved under the directory you passed to AgentWorkspace(...) or config_from_root(...).
  • MCP / CLI: same rule via AGENT_GODMODE_ROOT or --root (no .. escape).
  • read_file, write_file, and edit_file only touch UTF-8 text paths under that root; edit_file requires valid UTF-8 (strict decode).
  • run_command uses argv only (no shell). Optional allowlist via AGENT_GODMODE_ALLOWED_COMMANDS.
  • Subprocess inherits the current environment; avoid passing secrets you do not want child processes to see.

CLI

bash
agent-godmode --root D:/your/project

Runs the MCP server on stdio (default for Cursor).

Agent loop (conceptual)

  1. System = SYSTEM_PROMPT_V1 (+ optional suffix).
  2. User message + OPENAI_TOOL_DEFINITIONS → your LLM.
  3. For each tool_call, run WorkspaceTools.dispatch (or MCP call_tool) — including read_file, write_file, edit_file, list_files, and run_command as defined by the server.
  4. Append tool results; repeat until the model returns text without tools.

run_agent_loop implements steps 2–4 given your complete() function.

License

MIT

[MCP Badge]

[MCP Badge]

來源:README.md,提交 2763967

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.9最新Sep 16, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。