agent-godmode 0.1.1

MCP server and library: read/write files, run commands, list files — with strict prompts for user-provided LLMs.

mcp-agent-tools

Workspace-scoped MCP tools for building Cursor-style agents: read_file, write_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.

Install

pip install mcp-agent-tools

OpenAI walkthrough (Jupyter): samples/test_openai_agent.ipynb — mirrors the Tier B section below.

Editable / dev:

pip install -e ".[dev]"

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):

{
  "mcpServers": {
    "agent-tools": {
      "command": "mcp-agent-tools",
      "args": [],
      "env": {
        "MCP_AGENT_TOOLS_ROOT": "D:/your/project"
      }
    }
  }
}

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

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

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

Environment variables

Variable	Meaning
MCP_AGENT_TOOLS_ROOT	Required unless --root is passed. Absolute workspace root.
MCP_AGENT_TOOLS_MAX_READ_BYTES	Max bytes per read (default 512000).
MCP_AGENT_TOOLS_COMMAND_TIMEOUT	Subprocess timeout in seconds (default 120).
MCP_AGENT_TOOLS_MAX_COMMAND_OUTPUT_BYTES	Truncate stdout/stderr combined (default 256000).
MCP_AGENT_TOOLS_LIST_MAX_ENTRIES	Cap for list_files (default 2000).
MCP_AGENT_TOOLS_ALLOWED_COMMANDS	Comma-separated basenames allowed as argv[0] (e.g. python,uv,node). If unset, all commands allowed under the sandbox.

Tier B — Python app (same tools + prompts in-process)

A full runnable version of this flow (including pip cells) lives in samples/test_openai_agent.ipynb. Below is the same logic as plain Python you can paste into a script.

Ideas in the example

• One workspace root (here D:\Avi-assign — change it to your folder). AgentWorkspace only allows paths under that root.
• LLM → disk: read real files for context → call OpenAI → pass message.content only into write_file (no hand-written file body).
• Agent + tools: run_agent_loop + tools= so the model calls read_file / write_file itself; prompts insist the content argument of write_file is model-authored text.

Install

pip install mcp-agent-tools openai

Setup: workspace + seed file

from pathlib import Path

from openai import OpenAI

from mcp_agent_tools import AgentWorkspace, SYSTEM_PROMPT_V1, run_agent_loop

# Set OPENAI_API_KEY in your environment before running (recommended).
# For local experiments only: os.environ["OPENAI_API_KEY"] = "sk-..."  # do not commit real keys

client = OpenAI()
MODEL = "gpt-4o-mini"

WORK_DIR = Path(r"D:\Avi-assign")  # change to your workspace
WORK_DIR.mkdir(parents=True, exist_ok=True)

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 (first 25 lines) ---")
_listing = ws.list_files(".", recursive=False).strip().splitlines()
print("\n".join(_listing[:25]) + ("\n..." if len(_listing) > 25 else ""))

Example A — file body is only what the LLM returns (no tool calls)

context = ws.read_file("hello.txt")
user_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.")

ws.write_file("llm_generated_notes.md", generated, mode="overwrite")
print(ws.read_file("llm_generated_notes.md"))

Example B — agent loop: model calls tools and writes agent_notes.txt

def complete(messages, tools):
    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(answer)
if (WORK_DIR / "agent_notes.txt").exists():
    print(ws.read_file("agent_notes.txt"))

Optional limits on AgentWorkspace

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.

from mcp_agent_tools import WorkspaceTools, OPENAI_TOOL_DEFINITIONS, SYSTEM_PROMPT_V1
from mcp_agent_tools.config import config_from_root

tools = WorkspaceTools(config_from_root(r"D:\Avi-assign"))
print(tools.read_file("hello.txt"))

Compose the system message:

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

Imports reference

• AgentWorkspace — pass a directory path; use read_file / write_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 MCP_AGENT_TOOLS_ROOT or --root (no .. escape).
• run_command uses argv only (no shell). Optional allowlist via MCP_AGENT_TOOLS_ALLOWED_COMMANDS.
• Subprocess inherits the current environment; avoid passing secrets you do not want child processes to see.

CLI

mcp-agent-tools --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).
4. Append tool results; repeat until the model returns text without tools.

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

Publishing to PyPI

The distribution name in pyproject.toml is mcp-agent-tools. Before the first release, search https://pypi.org/project/mcp-agent-tools/ — if the name is taken, change name in pyproject.toml (and update pip install ... docs).

1. Account — Create an account on PyPI (enable 2FA). Optionally practice on TestPyPI.

2. API token — PyPI → Account settings → API tokens → scope “Entire account” or a token limited to this project after the first upload.

3. Version — Bump version = "0.1.0" in pyproject.toml for every new release (PEP 440, e.g. 0.1.1).

4. Build (from the repo root):

   pip install build twine
   python -m build
   

   This creates dist/mcp_agent_tools-<version>-py3-none-any.whl and a .tar.gz.

5. Check — twine check dist/*

6. Upload (test first) —

   twine upload --repository testpypi dist/*
   

   Install with: pip install -i https://test.pypi.org/simple/ mcp-agent-tools

7. Upload (production) —

   twine upload dist/*
   

   Twine will prompt for the username __token__ and password your PyPI API token.

After publishing, users install with:

pip install mcp-agent-tools

Trusted publishing (GitHub Actions → PyPI without a long-lived token) is described in the PyPI publishing guide.

License

MIT