Smart Assistant MCP

Turn a Windows developer workstation into a controlled MCP runtime for AI agents.

Smart Assistant MCP is a Windows-first MCP server focused on safe local development workflows: scoped filesystem access, durable command execution, bounded search, Windows operations, resource governance, and optional code/context backends.

It is designed for developers who want more than a thin collection of MCP tools. The runtime adds a control plane around local capabilities so agents can work on a workstation without treating unrestricted shell access as the default.

Current public release target: v0.1.0 · Python 3.12 · Apache-2.0 · Windows-first

What it demonstrates

This repository is both a usable MCP runtime and a reference implementation for several engineering problems that appear when agents are allowed to interact with a real developer machine:

• 37 MCP tools exposed through one governed endpoint;

• project-scoped filesystem access with traversal, symlink/reparse-point, and secret-path protections;

• durable process execution that survives HTTP disconnects;

• idempotent mutations and optimistic SHA-256 concurrency checks;

• persistent bounded search sessions with pagination and cancellation;

• Windows-native process, service, port, and scheduled-task inspection;

• resource admission control across RAM, CPU, disk, and optional GPU pressure;

• runtime capability truth that separates configured, available, and verified integrations;

• optional Serena, CodeGraph, Agent Memory, and Desktop Commander compatibility backends.

Application-specific connectors and personal automation modules are intentionally outside the scope of this public repository.

Related MCP server: Windows Scoped Remote MCP Server

Architecture

flowchart LR
    Client["MCP client / agent"] --> Edge["Loopback MCP edge"]
    Edge --> Auth["Bearer identity + scopes"]
    Auth --> Policy["Project & mutation policy"]
    Policy --> Governor["Resource governor"]

    Governor --> FS["Filesystem + durable search"]
    Governor --> Broker["Durable execution broker"]
    Governor --> Win["Windows operations"]
    Governor --> Wiki["Wiki / local context"]
    Governor --> Backends["Backend manager"]

    Backends --> Serena["Serena"]
    Backends --> Graph["CodeGraph"]
    Backends --> Memory["Agent Memory"]
    Backends --> Compat["Desktop compatibility"]

    Broker --> State[("SQLite state")]
    Broker --> Runner["Detached runner + Job Object"]
    Wiki --> FTS[("SQLite FTS")]

The important boundary is deliberate: project scoping is an application guardrail, not an operating-system sandbox. Native commands execute with the rights of the Windows account running the service.

For the complete design, see docs/ARCHITECTURE.md.

Why a control plane matters

A basic MCP server can expose read_file or run_command. A workstation runtime needs more guarantees.

Demo scenarios

1. Inspect a codebase without exposing the whole machine

Register one directory as a project, then use the built-in filesystem tools to list, read, and search it. Paths are relative to the project root and protected locations such as .ssh, .aws, .azure, .env, credential directories, and Git internals are rejected.

2. Start work once, reconnect later

execution_start persists an accepted command before it runs. The client can disconnect, reconnect, list executions, and continue reading stdout/stderr using byte cursors.

For synchronous-feeling workflows, execution_run submits through the same durable broker, waits briefly, and returns the current state without creating a second execution path.

3. Add developer intelligence as optional backends

The runtime can front external MCP processes such as Serena, CodeGraph, and Agent Memory. Each backend is independently enabled, resource-bounded, and restricted to an explicit tool allowlist.

See docs/INTEGRATIONS.md for the qualification model.

Public capability groups

The complete catalog is in docs/CAPABILITIES.md.

Quick start

Requirements:

• Windows 10/11;

• Python 3.12;

• PowerShell;

• optional external backends installed separately.

git clone https://github.com/mehdisafer/smart-assistant-mcp.git
cd smart-assistant-mcp

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade "pip>=26.2"
.\.venv\Scripts\python.exe -m pip install -e ".[test]"

.\scripts\bootstrap.ps1
.\scripts\run-local.ps1

The bootstrap creates:

• a local workspace/;

• config/runtime.json from the safe example;

• a random bearer token whose SHA-256 digest is stored in the ignored identity registry.

The token is displayed once. Store it in the MCP client or a secret manager.

The default configuration binds only to 127.0.0.1, exposes only the local workspace project, disables process termination, and leaves every optional backend disabled.

Security posture

The public configuration is intentionally conservative:

• loopback-only server;

• no direct public binding;

• explicit bearer identities and scopes;

• exact project grants, never wildcard project access;

• relative filesystem paths only;

• parent traversal and reparse points rejected;

• protected secret/config directories denied;

• process execution requires an absolute executable path;

• mutating projects are separately allowlisted;

• higher-risk process termination is disabled by default;

• third-party backends are disabled until explicitly configured.

Read docs/SECURITY.md before enabling remote access or additional projects.

Optional developer backends

Smart Assistant MCP does not vendor these projects. They run as independent MCP processes when explicitly enabled.

• Serena — symbol-aware navigation and LSP diagnostics.

• CodeGraph — repository-level graph exploration.

• Agent Memory — persistent historical/context retrieval.

• Desktop Commander compatibility — optional compatibility layer for richer file/document operations.

This separation keeps the core independently licensed and makes backend permissions visible in configuration.

See THIRD_PARTY.md and docs/LICENSING.md.

Engineering status

The public v0.1.0 baseline is intended to establish a clean, reproducible core rather than claim complete workstation automation.

Validated before publication:

• clean Python 3.12 installation;

• source compilation;

• public regression tests;

• Bandit with 0 medium / 0 high findings;

• dependency audit with no known vulnerabilities after packaging-tool upgrade;

• secret/private-environment scans on tracked files and Git history;

• Apache-2.0 package metadata and wheel inclusion.

Remaining work is tracked in docs/PUBLICATION_ROADMAP.md.

Repository map

src/smart_assistant_mcp/   MCP runtime and control plane
config/                    safe public configuration templates
scripts/                   bootstrap and local run scripts
tests/                     public regression tests
docs/                      architecture, security, integrations, roadmap
.github/workflows/         Windows CI
workspace/                 default isolated project root

License

Smart Assistant MCP is licensed under the Apache License 2.0. See LICENSE.

Third-party integrations remain governed by their own upstream licenses.