PersonalMCP
# PersonalMCP
A local Python MCP server that gives an MCP client (VS Code, Copilot CLI) read/write access to one approved workspace: file and directory CRUD, search, git, shell commands, Python tooling, data conversion, web fetch, HTTP testing, system diagnostics and a todo list (68 tools). It uses the official MCP Python SDK over stdio and does not invoke an LLM. All tools run under one security model: workspace confinement, protected-name denylist, secret redaction, hashed audit logging, size/time limits, and an optional operator policy. Set `read_only` for inspection only, or `allow_commands=false` to disable process execution. Tool groups are documented at `docs://tools` (or the `get_tool_docs` tool) and in [src/personal_mcp/toolkit/resources](src/personal_mcp/toolkit/resources).
## Requirements
- Python 3.11 or newer
- Git is optional; Git inspection is disabled when it is unavailable or the workspace is not itself a repository
- Install from the release ZIP for an offline installation, or install the pinned project dependencies from PyPI
## Run from a checkout
```powershell
python -m pip install .
python -m personal_mcp --workspace C:\path\to\workspace serve
```
```bash
python -m pip install .
python -m personal_mcp --workspace "$HOME/project" serve
```
The server defaults to the current directory when no workspace is supplied. Configuration can be passed as JSON with `--config`; `MCP_WORKSPACE_ROOT` is the only supported environment override. See [docs/configuration.md](docs/configuration.md).
## Administration
```text
python -m personal_mcp --version
python -m personal_mcp validate-config
python -m personal_mcp self-test
python -m personal_mcp print-client-config
python -m personal_mcp diagnostics
python -m personal_mcp capability-manifest
```
See [docs/installation.md](docs/installation.md), [docs/security-and-guardrails.md](docs/security-and-guardrails.md), and [docs/compatibility.md](docs/compatibility.md) before deployment. Manual GitHub Copilot and VS Code validation is documented in [tests/manual/github-copilot-vscode-validation.md](tests/manual/github-copilot-vscode-validation.md).
## Development
```text
python -m unittest discover -s tests -v
python scripts/validate/validate_docs.py
python scripts/build/build_release.py
```
This project is not affiliated with or an extension to GitHub Copilot or Visual Studio Code. See [SECURITY.md](SECURITY.md) for vulnerability reporting.
TDQS
Scored across 68 tools
Tools are grouped into clear domains, but several within-domain pairs overlap heavily: git_status vs git_repository_status, git_log vs git_recent_history, and git_diff vs git_diff_summary vs git_diff_stat. Descriptions help distinguish bounded/read-only variants, but an agent could still easily misselect among them.
All names are snake_case, which is consistent, but the structural convention is mixed: verb_noun (list_directory, read_text_file), noun_verb (todo_list, git_status), and noun_noun (service_status, git_repository_status) all appear. The domain prefixes help readability, but there is no single predictable pattern.
With 68 tools, the surface is extremely large even for a broad personal automation server, and several tools duplicate existing read-only git functionality. This is squarely in the 50+ extreme-count range and makes discovery and selection harder.
The server covers filesystem, search, shell, Python tooling, git, data conversion, web/API testing, diagnostics, todos, and system inspection with broad lifecycle support. The main gaps are git network/workflow operations such as clone/fetch/pull/merge and service or process control, though run_command provides a workaround.