pyddock 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. pyddock-0.1.0/.gitignore +32 -0
  2. pyddock-0.1.0/LICENSE +21 -0
  3. pyddock-0.1.0/PKG-INFO +286 -0
  4. pyddock-0.1.0/README.md +262 -0
  5. pyddock-0.1.0/pyproject.toml +49 -0
  6. pyddock-0.1.0/src/pyddock/__init__.py +8 -0
  7. pyddock-0.1.0/src/pyddock/_process_utils.py +88 -0
  8. pyddock-0.1.0/src/pyddock/_runtime.py +1975 -0
  9. pyddock-0.1.0/src/pyddock/ast_validator.py +172 -0
  10. pyddock-0.1.0/src/pyddock/cli.py +183 -0
  11. pyddock-0.1.0/src/pyddock/config.py +459 -0
  12. pyddock-0.1.0/src/pyddock/default_config.toml +219 -0
  13. pyddock-0.1.0/src/pyddock/executor.py +275 -0
  14. pyddock-0.1.0/src/pyddock/script_registry.py +172 -0
  15. pyddock-0.1.0/src/pyddock/server.py +449 -0
  16. pyddock-0.1.0/src/pyddock/shell_executor.py +414 -0
  17. pyddock-0.1.0/src/pyddock/tools/__init__.py +10 -0
  18. pyddock-0.1.0/src/pyddock/tools/fs_append.py +113 -0
  19. pyddock-0.1.0/src/pyddock/tools/fs_delete.py +97 -0
  20. pyddock-0.1.0/src/pyddock/tools/read_file.py +114 -0
  21. pyddock-0.1.0/src/pyddock/tools/stat_file.py +51 -0
  22. pyddock-0.1.0/src/pyddock/tools/str_replace.py +238 -0
  23. pyddock-0.1.0/src/pyddock/venv_manager.py +196 -0
  24. pyddock-0.1.0/tests/__init__.py +0 -0
  25. pyddock-0.1.0/tests/test_ast_properties.py +178 -0
  26. pyddock-0.1.0/tests/test_config.py +414 -0
  27. pyddock-0.1.0/tests/test_executor.py +270 -0
  28. pyddock-0.1.0/tests/test_file_tools.py +409 -0
  29. pyddock-0.1.0/tests/test_filesystem_guards.py +162 -0
  30. pyddock-0.1.0/tests/test_proxy_properties.py +138 -0
  31. pyddock-0.1.0/tests/test_realistic.py +230 -0
  32. pyddock-0.1.0/tests/test_runtime.py +692 -0
  33. pyddock-0.1.0/tests/test_security_guards.py +656 -0
  34. pyddock-0.1.0/tests/test_server.py +184 -0
  35. pyddock-0.1.0/tests/test_shell_arg_paths.py +380 -0
  36. pyddock-0.1.0/tests/test_shell_executor.py +372 -0
  37. pyddock-0.1.0/tests/test_shell_properties.py +276 -0
  38. pyddock-0.1.0/tests/test_subprocess_enforcement.py +551 -0
  39. pyddock-0.1.0/tests/test_subprocess_properties.py +126 -0
  40. pyddock-0.1.0/tests/test_subst_trusted_path.py +168 -0
  41. pyddock-0.1.0/tests/test_workspace_imports.py +852 -0
  42. pyddock-0.1.0/uv.lock +769 -0
@@ -0,0 +1,32 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ *.egg-info/
7
+ *.egg
8
+ dist/
9
+ build/
10
+
11
+ # Virtual environments
12
+ .venv/
13
+ .pyddock/venv/
14
+
15
+ # IDE
16
+ .idea/
17
+ .kiro/
18
+ .vscode/
19
+ *.swp
20
+ *.swo
21
+
22
+ # OS
23
+ .DS_Store
24
+ Thumbs.db
25
+
26
+ # Testing
27
+ .pytest_cache/
28
+ .coverage
29
+ htmlcov/
30
+
31
+ # Temp
32
+ .pyddock/tmp/
pyddock-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Anthony
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
pyddock-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,286 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyddock
3
+ Version: 0.1.0
4
+ Summary: MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls
5
+ Project-URL: Homepage, https://github.com/portablestew/pyddock
6
+ Project-URL: Repository, https://github.com/portablestew/pyddock
7
+ Project-URL: Issues, https://github.com/portablestew/pyddock/issues
8
+ Author: portablestew
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,ai,mcp,python,sandbox,shell
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Security
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Requires-Python: >=3.11
22
+ Requires-Dist: mcp>=1.0
23
+ Description-Content-Type: text/markdown
24
+
25
+ # pyddock
26
+
27
+ *py + paddock — an enclosed space where code can run freely within bounds. ([Worked great in Jurassic Park.](https://en.wikipedia.org/wiki/Jurassic_Park))*
28
+
29
+ MCP server that gives AI agents pre-approved `run_python`, `run_shell`, and file i/o tools. Safely replaces shell scripting for data processing, file analysis, computation, and external command execution — no user confirmation needed.
30
+
31
+ ## Why
32
+
33
+ Agents write shell snippets for structured tasks. Those snippets require user approval (workflow friction) or blind trust (security risk). Common alternatives each have limitations:
34
+
35
+ - **Trust specific command strings.** Agents produce variations or chain commands into ad-hoc scripts that break naive string matching, causing repeated approval prompts for equivalent operations.
36
+ - **Trust all shell execution.** Unsafe when the environment has access to production resources.
37
+ - **Full containerized sandbox (Docker).** Isolation cuts agents off from the dev workspace, host network, and local tooling. Restoring access requires per-project configuration that is brittle to maintain.
38
+ - **Larger agent framework with granular permissions.** High adoption cost for what should be a drop-in tool.
39
+
40
+ pyddock provides Python execution and shell command access with declarative policy controls. Policies are safe to auto-approve because side effects are scoped to the configured workspace.
41
+
42
+ **Intended use:** Trusted shell replacement for unattended agents in development environments. The full permission policy is reported in the MCP tool description, so agents know what is allowed before writing code. When a snippet does violate a policy, the error includes the specific rule and a recommended workaround. Agents adapt non-interactively rather than blocking on human approval.
43
+
44
+ **Replaces dedicated MCP servers:** A full Python environment means agents can call service APIs directly (boto3, p4python, etc.) under the same policy enforcement. This eliminates the need for separate MCP servers for AWS, Atlassian, Perforce, and similar services, and allows agents to compose multiple API calls in a single `run_python` invocation.
45
+
46
+ **Workspace scripts:** Scripts in a configured directory (e.g. `.kiro/scripts/`) are automatically trusted. Scripts authored for workspace agents require no additional pyddock configuration.
47
+
48
+ **Threat model:** Pyddock's guardrails keep *trustworthy local agents* out of trouble. A determined adversary may discover a jailbreak, or chain with other tools in the workspace for escalation and/or exfiltration. The Python sandbox contains extensive anti-jailbreak protections, but only as a first-line of defense against accidents and casual misuse. Pyddock does not claim to be a security boundary against targeted exploitation or public abuse. In other words, life finds a way.
49
+
50
+ ## Setup
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "pyddock": {
56
+ "command": "uvx",
57
+ "args": ["pyddock", "serve", "--workspace", "<path-to-workspace>"],
58
+ "autoApprove": ["run_python","run_shell","fs_read","fs_stat","fs_append","fs_delete","fs_str_replace"]
59
+ }
60
+ }
61
+ }
62
+ ```
63
+
64
+ ## Tool: `run_python`
65
+
66
+ | Parameter | Type | Description |
67
+ |-----------|------|-------------|
68
+ | `code` | string | Inline Python snippet |
69
+ | `file` | string | Path to a .py file (mutually exclusive with `code`) |
70
+ | `args` | string[] | Available as `sys.argv[1:]` |
71
+ | `timeout` | number | Seconds (default: 30) |
72
+
73
+ The last expression in your snippet is captured as RESULT (like a Jupyter cell) when it evaluates to a non-None value. Use `print()` for streaming output or a trailing expression for structured return values.
74
+
75
+ ## Tool: `run_shell`
76
+
77
+ | Parameter | Type | Description |
78
+ |-----------|------|-------------|
79
+ | `command` | string | Executable name or script path (must match a shell policy) |
80
+ | `args` | string[] | Arguments passed directly to the command (no shell interpretation) |
81
+ | `timeout` | number | Seconds (default: 30) |
82
+
83
+ Commands are executed directly — no shell interpretation, pipes, redirects, chaining, or variable expansion. Only commands matching a `[shell.*]` policy in your config are permitted. The tool is only registered when at least one `[shell.*]` section exists in the config.
84
+
85
+ Script files get automatic interpreter mapping: `.ps1` → powershell, `.py` → python, `.sh` → bash, `.bat` → cmd /c.
86
+
87
+ ## Output format
88
+
89
+ Both `run_python` and `run_shell` return human-readable text sections:
90
+
91
+ ```
92
+ --- RESULT ---
93
+ 42
94
+ --- STDOUT ---
95
+ Processing 10 files...
96
+ Done.
97
+ --- STDERR ---
98
+ Warning: deprecated API
99
+ --- EXIT CODE: 0 ---
100
+ ```
101
+
102
+ - Sections are omitted when empty (except EXIT CODE which is always present)
103
+ - RESULT only appears in `run_python` responses, when the last expression is non-None
104
+ - `run_shell` responses have STDOUT, STDERR, and EXIT CODE only
105
+
106
+ ## File Tools
107
+
108
+ Pyddock also exposes file I/O tools that execute through the same sandbox as `run_python` — same filesystem scoping, same protected directories, same policy enforcement. These are convenience shortcuts for common file operations; agents can't do anything they couldn't already do via `run_python` with `pathlib`. On failure, error messages include diagnostic context to guide the agent's next attempt.
109
+
110
+ - **`fs_read`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
111
+ - **`fs_stat`** — File metadata (exists, type, size, line count, modified). Returns `exists: false` for missing paths.
112
+ - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
113
+ - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
114
+ - **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
115
+
116
+ ## Security model
117
+
118
+ `run_python` enforcement:
119
+
120
+ - **AST validation** (pre-execution) — rejects disallowed imports, blocked calls (`eval`, `exec`, `compile`), and blocked attribute access (`__globals__`, `__subclasses__`, etc.)
121
+ - **Runtime enforcement** (in-subprocess) — import hook, filesystem scoping, `getattr`/`attrgetter` guards, factory proxies for library method restrictions, safe `sys`/`os`/`subprocess` module proxies
122
+
123
+ `run_shell` and subprocess enforcement:
124
+
125
+ - **Default deny** — any command not matching a `[shell.*]` config section is rejected outright
126
+ - **No shell interpretation** — commands execute via `subprocess.run(shell=False)`, preventing injection, pipes, redirects, and variable expansion
127
+ - **Argument validation** — per-command allow/deny regex patterns control which arguments are permitted
128
+ - **Argument path scanning** — args that look like filesystem paths are validated against protected directories and workspace boundaries (configurable via `arg_paths`)
129
+ - **Write protection** — path-like shell command regexes automatically generate write-deny rules for `run_python`, preventing write-then-execute privilege escalation
130
+ - **subprocess proxy** — `run_python` code has access to `subprocess.run()` and `subprocess.Popen()`, both validated against the same shell policies; `shell=True` and string commands are always rejected; `os.system()` is blocked
131
+
132
+ Writes are restricted to the workspace. The `.pyddock/` directory, pyddock source, and the Python stdlib directory are always write-protected (`.pyddock/tmp/` is the exception, used by tempfile). Reads are unrestricted by default but subject to filesystem guards.
133
+
134
+ **Filesystem guards** (`[filesystem.guards]`) provide regex-based path rules that apply to both reads and writes. Each pattern maps to a disposition: `"deny-agent"` (block agent code; trusted libraries bypass), `"deny-all"` (block unconditionally), `"workspace"` (allow only inside the workspace), or `"allow"` (permit unconditionally). First match listed in the toml wins. Assorted secrets are blocked by default (`~/.ssh/`, `~/.aws/credentials`, `~/.gnupg/`, etc.). `.env` files are restricted to workspace-only access.
135
+
136
+ ## Configuration
137
+
138
+ Configuration is resolved in two steps:
139
+
140
+ 1. **Base config:** `.pyddock/pyddock.toml` in your workspace (full replacement of the bundled default), or `default_config.toml` if no workspace config exists.
141
+ 2. **Overlay (optional):** `.pyddock/pyddock.override.toml` is deep-merged on top of the base. Only include sections/keys you want to change — everything else is inherited.
142
+
143
+ See `default_config.toml` for the full annotated reference. Key sections:
144
+
145
+ ```toml
146
+ [execution]
147
+ timeout = 30
148
+ max_timeout = 3600
149
+
150
+ [imports]
151
+ json = true
152
+ csv = true
153
+ pathlib = true
154
+ # ... (see default_config.toml for full list)
155
+ sys = true
156
+ os = true
157
+ subprocess = true
158
+ dateutil = "python-dateutil"
159
+ polars = true
160
+ boto3 = true
161
+
162
+ [filesystem]
163
+ writable_paths = ["."] # "." = workspace directory; "*" = unrestricted
164
+ readable_paths = ["*"]
165
+
166
+ [filesystem.guards] # regex → disposition (first match wins)
167
+ "/\\.ssh/" = "deny-agent"
168
+ "/\\.aws/credentials$" = "deny-agent"
169
+ "/\\.npmrc$" = "deny-all"
170
+ "/\\.env(\\.[^/]*)?$" = "workspace"
171
+
172
+ [ast]
173
+ block_calls = ["eval", "exec", "compile", "breakpoint", "__import__"]
174
+ block_attributes = ["__subclasses__", "__globals__", "__code__", "__bases__", "__mro__", "__closure__"]
175
+
176
+ [restrictions.polars]
177
+ mode = "allow"
178
+ module_deny = ["write_.*", "sink_.*"]
179
+ class_deny = ["write_.*", "sink_.*"]
180
+
181
+ [restrictions.boto3]
182
+ mode = "deny"
183
+ module_allow = ["client"]
184
+ class_allow = ["list_.*", "describe_.*", "get_.*", "head_.*", "scan", "query", "start_query", "stop_query"]
185
+
186
+ [shell.p4]
187
+ mode = "deny"
188
+ allow = ["filelog.*", "files.*", "describe.*", "changes.*", "print.*", "where.*", "info"]
189
+
190
+ [shell.git]
191
+ mode = "deny"
192
+ allow = ["status.*", "log.*", "diff.*", "show.*", "branch.*", "rev-parse.*"]
193
+
194
+ [shell.kiro-scripts]
195
+ command = "\\.kiro/scripts/.*"
196
+ mode = "allow"
197
+ deny = []
198
+ arg_paths = "protected"
199
+ ```
200
+
201
+ ### Import values
202
+
203
+ Modules are configured in `[imports]` by setting the import name (what you'd write after `import`) to a value:
204
+
205
+ ```toml
206
+ [imports]
207
+ json = true
208
+ pathlib = true
209
+ dateutil = "python-dateutil" # pip name differs from import name
210
+ invoice_parser = ".kiro/scripts/invoice-parser" # import invoice_parser
211
+ metrics_client = ".kiro/scripts/reporting/metrics-client" # import metrics_client
212
+ ```
213
+
214
+ - `true` — allowed module (import name == pip package name)
215
+ - `false` — revoked module
216
+ - `"<pip-name>"` — allowed module where the PyPI package name differs from the import name (e.g. `dateutil = "python-dateutil"`)
217
+ - `"<path>"` — workspace package installed via `pip install -e` at boot (string containing `/` or `\`, or starting with `.`)
218
+
219
+ Each workspace package must contain a `pyproject.toml`. Dependencies declared in `pyproject.toml` are resolved automatically during installation — transitive deps are available to the package at runtime (including lazy/deferred imports), but not directly importable by agent code unless explicitly listed.
220
+
221
+ Source code changes in workspace packages are picked up immediately (editable install). Metadata changes (e.g. adding new dependencies in `pyproject.toml`) require a server restart.
222
+
223
+ Workspace module directories are automatically write-protected to prevent code modification from within `run_python`.
224
+
225
+ ### Configuration override
226
+
227
+ A minimal `.pyddock/pyddock.override.toml` example — only include what you want to change:
228
+
229
+ ```toml
230
+ # .pyddock/pyddock.override.toml — only include what you want to change
231
+ [imports]
232
+ requests = true # add a module
233
+ boto3 = false # revoke a module
234
+
235
+ [execution]
236
+ timeout = 120 # override default 30s
237
+
238
+ [shell.npm]
239
+ command = "^npm$"
240
+ mode = "deny"
241
+ allow = ["run build.*", "test.*"]
242
+ ```
243
+
244
+ Merge semantics:
245
+
246
+ - **Scalars and lists** (timeout, writable_paths, block_calls): overlay value replaces base value.
247
+ - **Tables** (imports, restrictions, shell): merge by key — new keys are added, existing keys are overwritten, unmentioned keys are inherited.
248
+
249
+ ## Restrictions
250
+
251
+ Two modes for per-library restrictions:
252
+
253
+ - **deny** (with `module_allow` and `class_allow`): blocks all module-level access except functions matching `module_allow` patterns. Wraps allowed callables with a proxy so objects they return are restricted to methods matching `class_allow` patterns. Use for client-producing libraries (boto3, botocore).
254
+ - **allow** (with `module_deny` and `class_deny`): blocks specific module-level functions matching `module_deny` patterns and methods on classes matching `class_deny` patterns. Use for libraries where most operations are safe (polars, pandas).
255
+
256
+ ## Shell Policies
257
+
258
+ Each `[shell.<name>]` section defines a command execution policy:
259
+
260
+ - **command**: regex pattern matched against the command string (defaults to `^<name>$` if omitted)
261
+ - **mode**: `"deny"` (block all args except those matching `allow`) or `"allow"` (permit all args except those matching `deny`)
262
+ - **allow**: list of regex patterns for permitted argument strings (used with deny mode)
263
+ - **deny**: list of regex patterns for blocked argument strings (used with allow mode)
264
+ - **arg_paths**: controls path scanning for arguments that look like filesystem paths:
265
+ - `"workspace"` (default) — blocks args resolving outside the workspace or into protected dirs (`.pyddock/`, workspace modules, script dirs)
266
+ - `"protected"` — only blocks args targeting protected dirs; allows paths outside the workspace
267
+ - `"none"` — no path scanning (fully trusts the command)
268
+
269
+ Args are space-joined before matching: `["filelog", "//depot/..."]` becomes `"filelog //depot/..."`. All regexes use `re.match()` (implicitly anchored at start).
270
+
271
+ When `subprocess` is enabled in `[imports]`, `run_python` code can call `subprocess.run([...])` with the same policy enforcement and interpreter mapping. This is useful for composing multiple commands, processing output between calls, or passing environment variables dynamically.
272
+
273
+ ## CLI
274
+
275
+ ```sh
276
+ pyddock serve --workspace /path/to/project # MCP server (stdio)
277
+ pyddock run "2 + 2" # Direct execution
278
+ pyddock run script.py -- arg1 arg2 # File execution with args
279
+ ```
280
+
281
+ ## Development
282
+
283
+ ```sh
284
+ uv sync
285
+ uv run pytest
286
+ ```
@@ -0,0 +1,262 @@
1
+ # pyddock
2
+
3
+ *py + paddock — an enclosed space where code can run freely within bounds. ([Worked great in Jurassic Park.](https://en.wikipedia.org/wiki/Jurassic_Park))*
4
+
5
+ MCP server that gives AI agents pre-approved `run_python`, `run_shell`, and file i/o tools. Safely replaces shell scripting for data processing, file analysis, computation, and external command execution — no user confirmation needed.
6
+
7
+ ## Why
8
+
9
+ Agents write shell snippets for structured tasks. Those snippets require user approval (workflow friction) or blind trust (security risk). Common alternatives each have limitations:
10
+
11
+ - **Trust specific command strings.** Agents produce variations or chain commands into ad-hoc scripts that break naive string matching, causing repeated approval prompts for equivalent operations.
12
+ - **Trust all shell execution.** Unsafe when the environment has access to production resources.
13
+ - **Full containerized sandbox (Docker).** Isolation cuts agents off from the dev workspace, host network, and local tooling. Restoring access requires per-project configuration that is brittle to maintain.
14
+ - **Larger agent framework with granular permissions.** High adoption cost for what should be a drop-in tool.
15
+
16
+ pyddock provides Python execution and shell command access with declarative policy controls. Policies are safe to auto-approve because side effects are scoped to the configured workspace.
17
+
18
+ **Intended use:** Trusted shell replacement for unattended agents in development environments. The full permission policy is reported in the MCP tool description, so agents know what is allowed before writing code. When a snippet does violate a policy, the error includes the specific rule and a recommended workaround. Agents adapt non-interactively rather than blocking on human approval.
19
+
20
+ **Replaces dedicated MCP servers:** A full Python environment means agents can call service APIs directly (boto3, p4python, etc.) under the same policy enforcement. This eliminates the need for separate MCP servers for AWS, Atlassian, Perforce, and similar services, and allows agents to compose multiple API calls in a single `run_python` invocation.
21
+
22
+ **Workspace scripts:** Scripts in a configured directory (e.g. `.kiro/scripts/`) are automatically trusted. Scripts authored for workspace agents require no additional pyddock configuration.
23
+
24
+ **Threat model:** Pyddock's guardrails keep *trustworthy local agents* out of trouble. A determined adversary may discover a jailbreak, or chain with other tools in the workspace for escalation and/or exfiltration. The Python sandbox contains extensive anti-jailbreak protections, but only as a first-line of defense against accidents and casual misuse. Pyddock does not claim to be a security boundary against targeted exploitation or public abuse. In other words, life finds a way.
25
+
26
+ ## Setup
27
+
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "pyddock": {
32
+ "command": "uvx",
33
+ "args": ["pyddock", "serve", "--workspace", "<path-to-workspace>"],
34
+ "autoApprove": ["run_python","run_shell","fs_read","fs_stat","fs_append","fs_delete","fs_str_replace"]
35
+ }
36
+ }
37
+ }
38
+ ```
39
+
40
+ ## Tool: `run_python`
41
+
42
+ | Parameter | Type | Description |
43
+ |-----------|------|-------------|
44
+ | `code` | string | Inline Python snippet |
45
+ | `file` | string | Path to a .py file (mutually exclusive with `code`) |
46
+ | `args` | string[] | Available as `sys.argv[1:]` |
47
+ | `timeout` | number | Seconds (default: 30) |
48
+
49
+ The last expression in your snippet is captured as RESULT (like a Jupyter cell) when it evaluates to a non-None value. Use `print()` for streaming output or a trailing expression for structured return values.
50
+
51
+ ## Tool: `run_shell`
52
+
53
+ | Parameter | Type | Description |
54
+ |-----------|------|-------------|
55
+ | `command` | string | Executable name or script path (must match a shell policy) |
56
+ | `args` | string[] | Arguments passed directly to the command (no shell interpretation) |
57
+ | `timeout` | number | Seconds (default: 30) |
58
+
59
+ Commands are executed directly — no shell interpretation, pipes, redirects, chaining, or variable expansion. Only commands matching a `[shell.*]` policy in your config are permitted. The tool is only registered when at least one `[shell.*]` section exists in the config.
60
+
61
+ Script files get automatic interpreter mapping: `.ps1` → powershell, `.py` → python, `.sh` → bash, `.bat` → cmd /c.
62
+
63
+ ## Output format
64
+
65
+ Both `run_python` and `run_shell` return human-readable text sections:
66
+
67
+ ```
68
+ --- RESULT ---
69
+ 42
70
+ --- STDOUT ---
71
+ Processing 10 files...
72
+ Done.
73
+ --- STDERR ---
74
+ Warning: deprecated API
75
+ --- EXIT CODE: 0 ---
76
+ ```
77
+
78
+ - Sections are omitted when empty (except EXIT CODE which is always present)
79
+ - RESULT only appears in `run_python` responses, when the last expression is non-None
80
+ - `run_shell` responses have STDOUT, STDERR, and EXIT CODE only
81
+
82
+ ## File Tools
83
+
84
+ Pyddock also exposes file I/O tools that execute through the same sandbox as `run_python` — same filesystem scoping, same protected directories, same policy enforcement. These are convenience shortcuts for common file operations; agents can't do anything they couldn't already do via `run_python` with `pathlib`. On failure, error messages include diagnostic context to guide the agent's next attempt.
85
+
86
+ - **`fs_read`** — Read a text file. Lines are 1-indexed; negative start = tail. Truncates large output with a continuation hint.
87
+ - **`fs_stat`** — File metadata (exists, type, size, line count, modified). Returns `exists: false` for missing paths.
88
+ - **`fs_append`** — Append to a file (creates if missing). Returns a unified diff.
89
+ - **`fs_delete`** — Delete a file or empty directory. Returns a unified diff of removed content.
90
+ - **`fs_str_replace`** — Find-and-replace exact text (unique match required). Returns a unified diff, or match diagnostics on failure.
91
+
92
+ ## Security model
93
+
94
+ `run_python` enforcement:
95
+
96
+ - **AST validation** (pre-execution) — rejects disallowed imports, blocked calls (`eval`, `exec`, `compile`), and blocked attribute access (`__globals__`, `__subclasses__`, etc.)
97
+ - **Runtime enforcement** (in-subprocess) — import hook, filesystem scoping, `getattr`/`attrgetter` guards, factory proxies for library method restrictions, safe `sys`/`os`/`subprocess` module proxies
98
+
99
+ `run_shell` and subprocess enforcement:
100
+
101
+ - **Default deny** — any command not matching a `[shell.*]` config section is rejected outright
102
+ - **No shell interpretation** — commands execute via `subprocess.run(shell=False)`, preventing injection, pipes, redirects, and variable expansion
103
+ - **Argument validation** — per-command allow/deny regex patterns control which arguments are permitted
104
+ - **Argument path scanning** — args that look like filesystem paths are validated against protected directories and workspace boundaries (configurable via `arg_paths`)
105
+ - **Write protection** — path-like shell command regexes automatically generate write-deny rules for `run_python`, preventing write-then-execute privilege escalation
106
+ - **subprocess proxy** — `run_python` code has access to `subprocess.run()` and `subprocess.Popen()`, both validated against the same shell policies; `shell=True` and string commands are always rejected; `os.system()` is blocked
107
+
108
+ Writes are restricted to the workspace. The `.pyddock/` directory, pyddock source, and the Python stdlib directory are always write-protected (`.pyddock/tmp/` is the exception, used by tempfile). Reads are unrestricted by default but subject to filesystem guards.
109
+
110
+ **Filesystem guards** (`[filesystem.guards]`) provide regex-based path rules that apply to both reads and writes. Each pattern maps to a disposition: `"deny-agent"` (block agent code; trusted libraries bypass), `"deny-all"` (block unconditionally), `"workspace"` (allow only inside the workspace), or `"allow"` (permit unconditionally). First match listed in the toml wins. Assorted secrets are blocked by default (`~/.ssh/`, `~/.aws/credentials`, `~/.gnupg/`, etc.). `.env` files are restricted to workspace-only access.
111
+
112
+ ## Configuration
113
+
114
+ Configuration is resolved in two steps:
115
+
116
+ 1. **Base config:** `.pyddock/pyddock.toml` in your workspace (full replacement of the bundled default), or `default_config.toml` if no workspace config exists.
117
+ 2. **Overlay (optional):** `.pyddock/pyddock.override.toml` is deep-merged on top of the base. Only include sections/keys you want to change — everything else is inherited.
118
+
119
+ See `default_config.toml` for the full annotated reference. Key sections:
120
+
121
+ ```toml
122
+ [execution]
123
+ timeout = 30
124
+ max_timeout = 3600
125
+
126
+ [imports]
127
+ json = true
128
+ csv = true
129
+ pathlib = true
130
+ # ... (see default_config.toml for full list)
131
+ sys = true
132
+ os = true
133
+ subprocess = true
134
+ dateutil = "python-dateutil"
135
+ polars = true
136
+ boto3 = true
137
+
138
+ [filesystem]
139
+ writable_paths = ["."] # "." = workspace directory; "*" = unrestricted
140
+ readable_paths = ["*"]
141
+
142
+ [filesystem.guards] # regex → disposition (first match wins)
143
+ "/\\.ssh/" = "deny-agent"
144
+ "/\\.aws/credentials$" = "deny-agent"
145
+ "/\\.npmrc$" = "deny-all"
146
+ "/\\.env(\\.[^/]*)?$" = "workspace"
147
+
148
+ [ast]
149
+ block_calls = ["eval", "exec", "compile", "breakpoint", "__import__"]
150
+ block_attributes = ["__subclasses__", "__globals__", "__code__", "__bases__", "__mro__", "__closure__"]
151
+
152
+ [restrictions.polars]
153
+ mode = "allow"
154
+ module_deny = ["write_.*", "sink_.*"]
155
+ class_deny = ["write_.*", "sink_.*"]
156
+
157
+ [restrictions.boto3]
158
+ mode = "deny"
159
+ module_allow = ["client"]
160
+ class_allow = ["list_.*", "describe_.*", "get_.*", "head_.*", "scan", "query", "start_query", "stop_query"]
161
+
162
+ [shell.p4]
163
+ mode = "deny"
164
+ allow = ["filelog.*", "files.*", "describe.*", "changes.*", "print.*", "where.*", "info"]
165
+
166
+ [shell.git]
167
+ mode = "deny"
168
+ allow = ["status.*", "log.*", "diff.*", "show.*", "branch.*", "rev-parse.*"]
169
+
170
+ [shell.kiro-scripts]
171
+ command = "\\.kiro/scripts/.*"
172
+ mode = "allow"
173
+ deny = []
174
+ arg_paths = "protected"
175
+ ```
176
+
177
+ ### Import values
178
+
179
+ Modules are configured in `[imports]` by setting the import name (what you'd write after `import`) to a value:
180
+
181
+ ```toml
182
+ [imports]
183
+ json = true
184
+ pathlib = true
185
+ dateutil = "python-dateutil" # pip name differs from import name
186
+ invoice_parser = ".kiro/scripts/invoice-parser" # import invoice_parser
187
+ metrics_client = ".kiro/scripts/reporting/metrics-client" # import metrics_client
188
+ ```
189
+
190
+ - `true` — allowed module (import name == pip package name)
191
+ - `false` — revoked module
192
+ - `"<pip-name>"` — allowed module where the PyPI package name differs from the import name (e.g. `dateutil = "python-dateutil"`)
193
+ - `"<path>"` — workspace package installed via `pip install -e` at boot (string containing `/` or `\`, or starting with `.`)
194
+
195
+ Each workspace package must contain a `pyproject.toml`. Dependencies declared in `pyproject.toml` are resolved automatically during installation — transitive deps are available to the package at runtime (including lazy/deferred imports), but not directly importable by agent code unless explicitly listed.
196
+
197
+ Source code changes in workspace packages are picked up immediately (editable install). Metadata changes (e.g. adding new dependencies in `pyproject.toml`) require a server restart.
198
+
199
+ Workspace module directories are automatically write-protected to prevent code modification from within `run_python`.
200
+
201
+ ### Configuration override
202
+
203
+ A minimal `.pyddock/pyddock.override.toml` example — only include what you want to change:
204
+
205
+ ```toml
206
+ # .pyddock/pyddock.override.toml — only include what you want to change
207
+ [imports]
208
+ requests = true # add a module
209
+ boto3 = false # revoke a module
210
+
211
+ [execution]
212
+ timeout = 120 # override default 30s
213
+
214
+ [shell.npm]
215
+ command = "^npm$"
216
+ mode = "deny"
217
+ allow = ["run build.*", "test.*"]
218
+ ```
219
+
220
+ Merge semantics:
221
+
222
+ - **Scalars and lists** (timeout, writable_paths, block_calls): overlay value replaces base value.
223
+ - **Tables** (imports, restrictions, shell): merge by key — new keys are added, existing keys are overwritten, unmentioned keys are inherited.
224
+
225
+ ## Restrictions
226
+
227
+ Two modes for per-library restrictions:
228
+
229
+ - **deny** (with `module_allow` and `class_allow`): blocks all module-level access except functions matching `module_allow` patterns. Wraps allowed callables with a proxy so objects they return are restricted to methods matching `class_allow` patterns. Use for client-producing libraries (boto3, botocore).
230
+ - **allow** (with `module_deny` and `class_deny`): blocks specific module-level functions matching `module_deny` patterns and methods on classes matching `class_deny` patterns. Use for libraries where most operations are safe (polars, pandas).
231
+
232
+ ## Shell Policies
233
+
234
+ Each `[shell.<name>]` section defines a command execution policy:
235
+
236
+ - **command**: regex pattern matched against the command string (defaults to `^<name>$` if omitted)
237
+ - **mode**: `"deny"` (block all args except those matching `allow`) or `"allow"` (permit all args except those matching `deny`)
238
+ - **allow**: list of regex patterns for permitted argument strings (used with deny mode)
239
+ - **deny**: list of regex patterns for blocked argument strings (used with allow mode)
240
+ - **arg_paths**: controls path scanning for arguments that look like filesystem paths:
241
+ - `"workspace"` (default) — blocks args resolving outside the workspace or into protected dirs (`.pyddock/`, workspace modules, script dirs)
242
+ - `"protected"` — only blocks args targeting protected dirs; allows paths outside the workspace
243
+ - `"none"` — no path scanning (fully trusts the command)
244
+
245
+ Args are space-joined before matching: `["filelog", "//depot/..."]` becomes `"filelog //depot/..."`. All regexes use `re.match()` (implicitly anchored at start).
246
+
247
+ When `subprocess` is enabled in `[imports]`, `run_python` code can call `subprocess.run([...])` with the same policy enforcement and interpreter mapping. This is useful for composing multiple commands, processing output between calls, or passing environment variables dynamically.
248
+
249
+ ## CLI
250
+
251
+ ```sh
252
+ pyddock serve --workspace /path/to/project # MCP server (stdio)
253
+ pyddock run "2 + 2" # Direct execution
254
+ pyddock run script.py -- arg1 arg2 # File execution with args
255
+ ```
256
+
257
+ ## Development
258
+
259
+ ```sh
260
+ uv sync
261
+ uv run pytest
262
+ ```
@@ -0,0 +1,49 @@
1
+ [project]
2
+ name = "pyddock"
3
+ version = "0.1.0"
4
+ description = "MCP server that gives AI agents pre-approved Python, shell, and file I/O tools with declarative policy controls"
5
+ requires-python = ">=3.11"
6
+ license = "MIT"
7
+ readme = "README.md"
8
+ authors = [
9
+ { name = "portablestew" },
10
+ ]
11
+ keywords = ["mcp", "ai", "agents", "sandbox", "python", "shell"]
12
+ classifiers = [
13
+ "Development Status :: 3 - Alpha",
14
+ "Intended Audience :: Developers",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.11",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Topic :: Software Development :: Libraries",
21
+ "Topic :: Security",
22
+ ]
23
+ dependencies = [
24
+ "mcp>=1.0",
25
+ ]
26
+
27
+ [project.urls]
28
+ Homepage = "https://github.com/portablestew/pyddock"
29
+ Repository = "https://github.com/portablestew/pyddock"
30
+ Issues = "https://github.com/portablestew/pyddock/issues"
31
+
32
+ [project.scripts]
33
+ pyddock = "pyddock.cli:main"
34
+
35
+ [build-system]
36
+ requires = ["hatchling"]
37
+ build-backend = "hatchling.build"
38
+
39
+ [tool.hatch.build.targets.wheel]
40
+ packages = ["src/pyddock"]
41
+
42
+ [tool.pytest.ini_options]
43
+ testpaths = ["tests"]
44
+
45
+ [dependency-groups]
46
+ dev = [
47
+ "pytest",
48
+ "hypothesis",
49
+ ]
@@ -0,0 +1,8 @@
1
+ """pyddock — policy-controlled Python execution via MCP."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ # Filename used for compile() when executing agent snippets.
6
+ # Used by executor (compile source), runtime (stack inspection to identify
7
+ # agent code vs trusted library code), and tests.
8
+ SNIPPET_FILENAME = "<snippet>"