
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.
概覽
沙箱式工作區 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。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 agent-godmode,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
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
Editable / 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.
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):
Or with an explicit CLI root (overrides env for that process):
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
Tier B — Python app (in-process + OpenAI)
Design notes
- Workspace root — Examples use
D:\Avi-assignas a placeholder; pointWORK_DIRat any directory you control. - API key policy —
OPENAI_API_KEYis required only for Chat Completions. Imports setclient = OpenAI() if HAS_OPENAI_KEY else None; workspace setup and directedit_filerun without a key. - Model-authored I/O — For
write_file, persist only text returned by the model. Foredit_file, the model must copyold_stringexactly fromread_file(seeSYSTEM_PROMPT_V1).
1. Install dependencies
In a shell or any interactive Python session:
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
3. Workspace bootstrap and seed file
4. LLM-authored file body (no tool calls)
Requires OPENAI_API_KEY. Skip if you are only exercising tools without the API.
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).
6. Agent loop: model calls write_file
Requires OPENAI_API_KEY.
7. Agent loop: model calls edit_file
Requires OPENAI_API_KEY and the complete function from §6.
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
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.
Compose the system message:
Imports reference
AgentWorkspace— pass a directory path; useread_file/write_file/edit_file/list_files/run_commandon that tree onlySYSTEM_PROMPT_V1,SYSTEM_PROMPT_CHANGELOG,TOOL_DESCRIPTIONSOPENAI_TOOL_DEFINITIONS— same shapes as MCP tools (fortools=in chat completions)build_server(config)— build aFastMCPapp (stdio viabuild_server(cfg).run())run_agent_loop— minimal multi-turn executor with yourcompletecallable (acceptsWorkspaceConfigorAgentWorkspace)
Safety model
- Python: all paths are resolved under the directory you passed to
AgentWorkspace(...)orconfig_from_root(...). - MCP / CLI: same rule via
AGENT_GODMODE_ROOTor--root(no..escape). read_file,write_file, andedit_fileonly touch UTF-8 text paths under that root;edit_filerequires valid UTF-8 (strict decode).run_commandusesargvonly (no shell). Optional allowlist viaAGENT_GODMODE_ALLOWED_COMMANDS.- Subprocess inherits the current environment; avoid passing secrets you do not want child processes to see.
CLI
Runs the MCP server on stdio (default for Cursor).
Agent loop (conceptual)
- System =
SYSTEM_PROMPT_V1(+ optional suffix). - User message +
OPENAI_TOOL_DEFINITIONS→ your LLM. - For each
tool_call, runWorkspaceTools.dispatch(or MCPcall_tool) — includingread_file,write_file,edit_file,list_files, andrun_commandas defined by the server. - Append tool results; repeat until the model returns text without tools.
run_agent_loop implements steps 2–4 given your complete() function.
License
MIT
來源:README.md,提交 2763967
工具
0版本歷史
1- v0.1.9最新Sep 16, 2026
評分
已滿足適用檢查項的 40%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分
請在儲存庫或註冊中心條目中宣告授權條款。
