penr-oz MCP Server

A FastMCP-based server for the penr-oz project with secure sandboxed filesystem operations. This repository provides tools for reading files and listing directories within a protected sandbox environment.

Install

Create and activate a virtual environment first:

python3 -m venv .venv
source .venv/bin/activate

pip install -e .

For development and testing:

pip install -e ".[dev]"

Run

python server.py             # stdio server
fastmcp run server.py        # if using the FastMCP CLI

Features

Core Reasoning Prompts

The server provides a curated collection of reusable MCP prompts demonstrating best practices for common reasoning and analysis tasks.

Available Prompts

summarize_text(text: str)

• Generate concise summaries of documents and articles
• Extracts key points and main ideas from text content
• Useful for: Documentation review, article analysis, content condensation

extract_tasks(text: str)

• Identify actionable tasks and TODOs from text
• Parses meeting notes, documentation, and messages for work items
• Formats tasks with deadlines and assignees when mentioned
• Useful for: Meeting notes processing, project planning, task tracking

analyze_code(code: str, language: str = "python")

• Comprehensive code quality and structure analysis
• Identifies potential bugs, code smells, and security vulnerabilities
• Provides performance considerations and improvement suggestions
• Useful for: Code reviews, technical debt assessment, learning best practices

write_design_doc(feature_description: str, context: str = "")

• Creates detailed technical design documents
• Covers architecture, implementation approach, and trade-offs
• Includes sections for security, testing, and risk analysis
• Useful for: Feature planning, system design, architectural decisions

refactor_instructions(code: str, issues: str, language: str = "python")

• Generates step-by-step refactoring guidance
• Explains rationale for each improvement
• Provides refactored code with risk considerations
• Useful for: Technical debt resolution, code modernization, pattern improvements

Backward Compatibility

summarize_prompt(text: str) - Deprecated

• Legacy alias for summarize_text()
• Maintained for backward compatibility with existing MCP clients
• Use summarize_text() for new integrations

API Integration Tools

The server provides tools for integrating with external HTTP APIs, demonstrating asynchronous operations with comprehensive error handling.

Tools

fetch_json(url: str, timeout: float = 10.0)

• Fetches JSON data from public HTTP APIs
• Supports asynchronous operations with configurable timeout
• Validates URLs and handles errors gracefully
• Example: fetch_json("https://api.github.com/repos/python/cpython")

Error Handling:

• InvalidURLError: Malformed URLs or unsupported schemes
• TimeoutError: Request exceeds timeout duration (default: 10s)
• HTTPError: Server returns error status (4xx, 5xx)
• JSONDecodeError: Response is not valid JSON
• APIError: Other network or request errors

Usage Examples:

# Fetch repository information
await fetch_json("https://api.github.com/repos/python/cpython")

# With custom timeout
await fetch_json("https://api.example.com/data", timeout=5.0)

Out of Scope:

• Authentication and secrets management
• Webhooks or streaming
• Non-JSON responses

Sandboxed Filesystem Access

The server provides secure, read-only access to files within a configured sandbox directory (./sandbox/). All file paths are validated to prevent directory traversal attacks.

Tools

list_files(path: str = "")

• Lists files and directories within the sandbox
• Returns metadata including name, type, path, and size
• Example: list_files("docs") to list the docs subdirectory

read_text_file(path: str)

• Reads UTF-8 text content from files within the sandbox
• Raises errors for non-existent files, directories, or invalid paths
• Example: read_text_file("welcome.txt")

Resources

ozfs://{path}

• Read-only file access via the ozfs:// protocol
• Example: ozfs://docs/guide.md returns the file contents

Security

• All paths are restricted to the ./sandbox/ directory
• Directory traversal attempts (e.g., ../) are blocked
• Paths are validated and resolved before access
• Only UTF-8 text files can be read

Structured Validation (Pydantic)

All tools and resources use Pydantic models for input validation. Invalid inputs return structured error messages before any business logic runs.

Input Schemas

ListFilesInput

{"path": "docs"}

• path (string, default: "") — Relative path within sandbox

ReadTextFileInput

{"path": "welcome.txt"}

• path (string, required, min length: 1) — Relative path to file within sandbox

FetchJsonInput

{"url": "https://api.github.com/repos/python/cpython", "timeout": 10.0}

• url (string, required, min length: 1) — HTTP(S) URL to fetch
• timeout (float, default: 10.0, range: (0, 300]) — Request timeout in seconds

OzfsResourceInput

{"path": "docs/guide.md"}

• path (string, required, min length: 1) — File path within sandbox

Output Schemas

FileEntry

{"name": "welcome.txt", "type": "file", "path": "welcome.txt", "size": 128}

• name (string) — File or directory name
• type (string) — "file" or "directory"
• path (string) — Relative path within sandbox
• size (int or null) — File size in bytes (null for directories)

Error Format

Invalid inputs return structured errors:

Validation error: 1 issue(s) found
  - path: String should have at least 1 character

Project layout

penr-oz-mcp-server/
|-- pyproject.toml
|-- README.md
|-- server.py
|-- app/
|   |-- __init__.py
|   |-- api.py             # API integration tools (fetch_json)
|   |-- config.py          # Server configuration and sandbox settings
|   |-- errors.py          # Centralized validation error handling
|   |-- filesystem.py      # Filesystem operations with security validation
|   |-- models.py          # Pydantic models for input/output validation
|   |-- tools.py           # MCP tools (ping, list_files, read_text_file)
|   |-- resources.py       # MCP resources (info, ozfs://)
|   `-- prompts.py         # MCP prompt templates
|-- sandbox/               # Sandboxed filesystem directory
|   |-- README.md
|   |-- welcome.txt
|   |-- docs/
|   `-- data/
`-- tests/
    |-- test_server_smoke.py
    |-- test_filesystem.py # Filesystem security and functionality tests
    |-- test_api.py        # API integration tests
    |-- test_prompts.py    # Prompt template tests
    `-- test_models.py     # Pydantic model and validation tests

Modules

• app/api.py - API integration tools for external HTTP services (fetch_json)
• app/config.py - Server metadata, environment flags, and sandbox configuration
• app/errors.py - Centralized validation error formatting and extraction
• app/filesystem.py - Secure filesystem operations with path validation
• app/models.py - Pydantic models for tool/resource input and output validation
• app/tools.py - MCP tools (ping, list_files, read_text_file)
• app/resources.py - MCP resources (info, ozfs://)
• app/prompts.py - MCP prompt templates
• server.py - Server initialization and component registration

Adding tools, resources, and prompts

Define a new tool/resource/prompt in the relevant module, then register it in server.py.

Example registration:

from app.tools import ping
mcp.add_tool(ping)

Testing

Run the test suite locally:

pytest

Continuous Integration

This project uses GitHub Actions to automatically run tests on every push and pull request. The CI workflow tests the codebase against Python 3.10, 3.11, and 3.12 to ensure compatibility across versions.

Tests must pass before pull requests can be merged. You can view the test results in the Actions tab or by clicking the badge at the top of this README.