# 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.