MCP Files MCP Server

MCP Files MCP Server

MCP Files exposes a constrained filesystem workspace (notes, knowledge bases, code artifacts) to LLM agents and automations. It supports stdio and remote HTTP mode.

Features

• Tool suite for listing, reading, writing, patching, deleting, and stat’ing files and project directory helpers.
• Per API key roots, extension whitelists, recursive-delete flags, quotas, and logging overrides.
• Structured logging/tracing with per security domain toggles and optional dedicated log files.

Installation

Either from PyPi

pip install mcpfiles

or via

git clone git@github.com:tspspi/mcpfiles.git
pip install -e .

Quick Start

1. Create a configuration file at ~/.config/mcpfiles.conf (or another path). Each entry in api_keys defines a root directory and permissions.
2. Run in stdio mode (default):

   mcpfiles [--config ~/.config/mcpfiles.conf]
   

   This binds the server to the root defined in the stdio block.
3. Run in remote HTTP mode:

   mcpfiles --remote
   

   The --remote flag is shorthand for --transport remotehttp and requires remote_server and api_keys blocks in the configuration file. Authentication accepts Authorization: Bearer, X-API-Key, or ?api_key= query string tokens.
4. Generate or rotate an API key for an existing entry:

   mcpfiles --genkey knowledge-base
   

   The command prints the plaintext secret once once on stdout and patches the matching api_keys[].kdf configuration.

Logging & Tracing

• Global defaults live under the top-level logging block. Per-key overrides inherit those defaults and may specify their own log file, categories (trace_access, trace_write, trace_delete, trace_metadata) and debug_all.
• Each MCP tool invocation emits one structured log entry containing the key ID, optional project ID, category, path, status and compact metrics (bytes written, entries listed, etc.).

Configuration

The default path for the configuration file is ~/.config/mcpfiles.conf. This path can be overriden with --config /path/to/config.json. To generate API keys one can utilize

mcpfiles --genkey <id>

An example is shown below:

{
  "mode": "remotehttp",
  "stdio": {
    "root": "/srv/mcpfiles/stdio",
    "projects_enabled": false,
    "extension_whitelist": [".md", ".txt", ".json"],
    "mime_validation": true,
    "allow_nonempty_delete": false,
    "immutable_paths": ["reference"],
    "quota": { "soft_limit_bytes": 268435456, "hard_limit_bytes": 322122547 },
    "logging": { "level": "INFO", "trace_access": true, "trace_write": true }
  },
  "logging": {
    "level": "INFO",
    "logfile": "/var/log/mcpfiles/main.log",
    "trace_access": true,
    "trace_write": true,
    "trace_delete": false,
    "trace_metadata": false,
    "debug_all": false
  },
  "remote_server": {
    "transport": { "uds": "/var/run/mcpfiles.sock" }
  },
  "api_keys": [
    {
      "id": "knowledge-base",
      "kdf": { "...": "..." },
      "root": "/srv/mcpfiles/agentA",
      "projects_enabled": true,
      "extension_whitelist": [".md", ".txt"],
      "mime_validation": true,
      "allow_nonempty_delete": false,
      "immutable_paths": ["reference"],
      "quota": { "soft_limit_bytes": 536870912, "hard_limit_bytes": 644245094 },
      "logging": { "logfile": "/var/log/mcpfiles/agentA.log" }
    }
  ]
}

Workspace Model

• Each stdio run is limited to the root resolved from the stdio block
• Remote mode: Every API key maps to a root directory. When project_id is provided, the server resolves into <root>/.projects/<uuid>/. Access to .projects outside the requested UUID is denied.
• An optional extension whitelist per root ensures agents only create/modify allowed file types (suffix checks plus optional file --mime-type verification when mime_validation is enabled).
• Optional quotas (soft_limit_bytes, hard_limit_bytes) cap total storage consumption per key/project. Hard limits block writes. Soft limits only log events (no response flag), letting agents query usage on demand.
• Hidden .metadata/usage.json directories store accounting data and are automatically excluded from MCP listings/reads. Manual tampering is prevented by treating .metadata as immutable.
• Immutable paths (relative to the key/project root) can expose reference material while prohibiting writes; mutation requests targeting these paths return an authorization error.
• Recursive deletions require allow_nonempty_delete=true in the key config; otherwise only empty directories can be removed.

FreeBSD Daemon Setup

• Copy the sample rc.d script (contrib/freebsd/mcpfiles) into /usr/local/etc/rc.d/mcpfiles and make it executable:

install -m 755 contrib/freebsd/mcpfiles /usr/local/etc/rc.d/mcpfiles

• Create a dedicated runtime account with no login shell (adjust UID/GID as needed):

pw useradd mcpfiles -d /nonexistent -s /usr/sbin/nolo