mcpserve

A production-quality Model Context Protocol (MCP) server in Go — exposing file system tools and note resources over JSON-RPC 2.0 stdio transport.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants like Claude interact with external tools and data sources through a structured JSON-RPC 2.0 interface. MCP servers expose tools (actions the AI can invoke) and resources (data the AI can read), enabling safe, sandboxed access to local systems.

Features

8 built-in tools — file I/O, directory listing, search, and markdown note management
Resource providers — serve files and notes as readable resources with URI addressing
JSON-RPC 2.0 over stdio — standard MCP transport; works with any compliant client
Path sandboxing — all file operations are confined to a configurable root directory
JSON Schema validation — tool inputs are validated against schemas before execution
Zero external dependencies — only the Go standard library
Graceful shutdown — handles SIGINT/SIGTERM for clean process termination
Configurable via environment — root directory, notes directory, and log level

Architecture

┌─────────────────────────────────────────────────┐
│                  Claude / AI Client              │
└──────────────────────┬──────────────────────────┘
                       │ JSON-RPC 2.0 (stdin/stdout)
┌──────────────────────▼──────────────────────────┐
│                 StdioTransport                   │
│          (newline-delimited JSON)                │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│                   Server                         │
│         (method dispatch + protocol)             │
├─────────────────┬───────────────────────────────┤
│   ToolRegistry  │      ResourceProvider          │
├────────┬────────┼──────────┬────────────────────┤
│  File  │ Notes  │   File   │      Notes         │
│ Tools  │ Tools  │ Provider │     Provider        │
└────────┴────────┴──────────┴────────────────────┘
         │                    │
    ┌────▼────┐          ┌───▼────┐
    │  Root   │          │ Notes  │
    │  Dir    │          │  Dir   │
    └─────────┘          └────────┘

Quick Start

# Clone and build
git clone https://github.com/devaloi/mcpserve.git
cd mcpserve
make build

# Run with defaults (current directory as root)
./bin/mcpserve

# Run with custom configuration
MCPSERVE_ROOT_DIR=~/projects \
MCPSERVE_NOTES_DIR=~/notes \
MCPSERVE_LOG_LEVEL=debug \
./bin/mcpserve

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcpserve": {
      "command": "/path/to/mcpserve",
      "env": {
        "MCPSERVE_ROOT_DIR": "/Users/you/projects",
        "MCPSERVE_NOTES_DIR": "/Users/you/notes"
      }
    }
  }
}

On macOS, this file is located at ~/Library/Application Support/Claude/claude_desktop_config.json.

Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | read_file | Read file contents (max 1MB) | path | | write_file | Write content to a file, creating directories as needed | path, content | | list_directory | List entries in a directory | path (optional: recursive) | | search_files | Search for files matching a glob pattern | path, pattern | | create_note | Create a markdown note with YAML frontmatter | title, content (optional: tags) | | read_note | Read a note by title | title | | list_notes | List notes, optionally filtered by tag | (optional: tag) | | search_notes | Search notes by substring in title and content | query |

Resources

| URI Pattern | Description | MIME Type | |-------------|-------------|-----------| | file:///{path} | Files under the root directory | Auto-detected by extension | | notes:///{slug} | Markdown notes by slug | text/markdown |

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | MCPSERVE_ROOT_DIR | . (current directory) | Root directory for file tools and file resources | | MCPSERVE_NOTES_DIR | $ROOT_DIR/notes | Directory for note storage | | MCPSERVE_LOG_LEVEL | info | Log verbosity level |

Development

Prerequisites: Go 1.22+

make build          # Build binary to bin/mcpserve
make test           # Run tests with race detection
make lint           # Run golangci-lint
make cover          # Generate coverage report
make clean          # Remove build artifacts

Project Structure

mcpserve/
├── cmd/mcpserve/           # Entry point — config, wiring, signal handling
│   └── main.go
├── internal/
│   ├── protocol/           # JSON-RPC 2.0 types and encoding
│   │   ├── types.go
│   │   └── jsonrpc.go
│   ├── transport/          # Transport interface and stdio implementation
│   │   ├── transport.go
│   │   └── stdio.go
│   ├── server/             # MCP server core — dispatch, handlers
│   │   ├── server.go
│   │   ├── handler.go
│   │   └── integration_test.go
│   ├── tools/              # Tool registry and built-in tools
│   │   ├── registry.go
│   │   ├── filesystem.go
│   │   └── notes.go
│   ├── resources/          # Resource providers
│   │   ├── provider.go
│   │   ├── fileprovider.go
│   │   ├── notesprovider.go
│   │   └── composite.go
│   └── schema/             # JSON Schema validation (Draft 7 subset)
│       └── validator.go
├── testdata/               # Test fixtures
├── docs/                   # Documentation and specs
├── Makefile
├── go.mod
└── LICENSE

Design Decisions

Zero external dependencies — the entire server, including JSON Schema validation, is implemented with the Go standard library. This minimizes supply chain risk and keeps the binary small.
Hand-rolled JSON Schema validator — supports the Draft 7 subset needed for MCP tool schemas (type, required, properties, enum, min/max constraints) without pulling in a full schema library.
Interface-driven architecture — ToolRegistry, ResourceProvider, and Transport are all interfaces, making every layer independently testable and replaceable.
Composite resource provider — multiple URI schemes (file:///, notes:///) are handled by composing providers rather than building a monolithic resource handler.
Path sandboxing — all file system access resolves paths against a root directory and rejects traversal attempts, preventing the AI from accessing files outside the sandbox.
Stderr for logging — stdout is exclusively reserved for the JSON-RPC 2.0 protocol stream; all diagnostic output goes to stderr.

License

MIT — see LICENSE for details.

MCP Servers