Shelv MCP Server
# @shelv/mcp
MCP server for Shelv shelf operations.
## Links
- Website: [shelv.dev](https://shelv.dev)
- Docs: [docs.shelv.dev/guides/mcp-server](https://docs.shelv.dev/guides/mcp-server)
- npm: [npmjs.com/package/@shelv/mcp](https://www.npmjs.com/package/@shelv/mcp)
- Source: [github.com/shelv-dev/shelv-mcp](https://github.com/shelv-dev/shelv-mcp)
## Install
```bash
pnpm add @shelv/mcp
```
```bash
npm install @shelv/mcp
```
```bash
npx @shelv/mcp
```
## Environment
- `SHELV_API_KEY` for stdio mode
- `SHELV_MCP_TRANSPORT=stdio|http` (defaults to `stdio`)
- `SHELV_MCP_HTTP_HOST` (defaults to `127.0.0.1`)
- `SHELV_MCP_HTTP_PORT` (defaults to `3334`)
- `SHELV_MCP_ENABLE_WRITE_TOOLS=true` to enable `create_shelf` and `hydrate_shelf`
- `SHELV_MCP_SEARCH_MAX_FILES` (defaults to `500`)
- `SHELV_MCP_SEARCH_MAX_BYTES` (defaults to `5000000`)
- `SHELV_MCP_SEARCH_MAX_MATCHES` (defaults to `200`)
- `SHELV_MCP_READ_MAX_BYTES` (defaults to `250000`)
## Run
```bash
shelv-mcp
```
```bash
SHELV_MCP_TRANSPORT=http SHELV_MCP_HTTP_PORT=3334 shelv-mcp
```
In HTTP mode, send `Authorization: Bearer sk_...` on each request unless
`SHELV_API_KEY` is configured as a startup fallback.
## Tools
- `list_shelves`
- `get_shelf_tree`
- `read_shelf_file`
- `search_shelf`
Write tools are disabled by default and become available only when
`SHELV_MCP_ENABLE_WRITE_TOOLS=true`:
- `create_shelf`
- `hydrate_shelf`
## License
Apache-2.0.
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: list_shelves enumerates available shelves, get_shelf_tree retrieves a full shelf's structure and contents, read_shelf_file accesses a single file, and search_shelf performs text searches across files. There is no overlap in functionality, making tool selection straightforward for an agent.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., list_shelves, get_shelf_tree, read_shelf_file, search_shelf). The naming is predictable and readable, with verbs like 'list', 'get', 'read', and 'search' appropriately describing the actions.
With 4 tools, the server is well-scoped for its purpose of managing shelves and files. Each tool serves a distinct and necessary function, covering listing, retrieval, reading, and searching without being overly sparse or bloated.
The toolset provides strong coverage for core operations like listing, reading, and searching shelves and files. However, there are minor gaps in CRUD/lifecycle coverage, such as no tools for creating, updating, or deleting shelves or files, which agents might need to work around for full management tasks.