shelby-mcp

A local-first Shelby MCP server for AI agents that need safe, typed access to Shelby storage workflows.

shelby-mcp is a backend/tooling-first repository, not a dashboard-first app. It gives MCP-compatible clients a serious Shelby integration surface with a strict filesystem sandbox, a fully working mock provider, an honest real-provider path, and an architecture that is ready to grow into HTTP transport, auth, media, and multi-user features later.

The MCP server, packages, docs, and tests live in the main repository structure. The static project website for shelby-mcp.okwn.cc now lives in `web-app/` and can be deployed independently as a lightweight landing page for the repository.

> Publish status > > Ready to publish publicly as an experimental repository. > Mock mode is mature and validated. Real provider mode is credible and implemented against the official Shelby SDK, but it is still experimental and not yet production-mature. CI is prepared for both Ubuntu and Windows, and the repo now includes an explicit real-provider smoke harness.

Fastest path from clone to a working local MCP server:

npm install
npm run setup
npm run dev:mock

What this gives you:

• a .env file copied from .env.example only if you do not already have one
• a prepared SHELBY_WORKDIR sandbox
• initialized mock storage and temp directories
• a running STDIO MCP server backed by the mock provider

First things to inspect from your MCP client:

• shelby_healthcheck
• shelby_get_safe_path_status