io.github.Studio-Moser/shelbymcp
Knowledge-graph memory server for AI tools via MCP
Open source Open in the app JSON README (API)
About
Knowledge-graph memory server for AI tools via MCP
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- studio-moser
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.4
- Last push
- 2026-08-27T15:07:16Z
- Repository state
- ativo
- Language
- Rust
- License
- MIT
- Added
- 2026-08-29 03:02:16
- Updated
- 2026-08-29 03:02:16
- Origin id
io.github.Studio-Moser/shelbymcp
README
<p align="center"> <img src="docs/assets/shelby-mcp-header.png" alt="ShelbyMCP" width="720" /> </p> <p align="center"> <strong>Local knowledge-graph memory for AI tools, implemented as one Rust binary.</strong> </p> ShelbyMCP gives MCP-compatible agents durable memory across sessions. Thoughts live in a local SQLite database with FTS5 search, optional vectors, typed graph edges, project scope, trust fencing, and curated context briefs. The server performs no inference and makes no model API calls. ## Quick start Run the platform-native binary through npm: ```bash npx -y shelbymcp --version npx -y shelbymcp ``` The default stdio server stores data at `~/.shelbymcp/memory.db`. Existing databases created by ShelbyMCP schema v18 open unchanged. Package-first integrations are included in the protected `v0.4.0` release: | Client | Release package | |---|---| | ChatGPT / Codex | `shelbymcp-codex-0.4.0.zip` | | Claude Code | `shelbymcp-claude-code-0.4.0.zip` | | Cursor and Agent Plugins clients | `shelbymcp-agent-plugin-0.4.0.zip` | | Gemini CLI | `shelbymcp-gemini-0.4.0.zip` | | Antigravity | `shelbymcp-antigravity-0.4.0.zip` | | Claude Desktop | `shelbymcp-claude-desktop-<platform>-0.4.0.mcpb` | | Devin | `shelbymcp-devin-0.4.0.zip` | Use `shelby-mcp setup <client>` only when the client package or marketplace entry is not available yet. The fallback supports `claude-code`, `claude-desktop`, `cursor`, `codex`, `gemini`, and `antigravity`; `devin` directs you to its organization-managed marketplace, while `windsurf` keeps the legacy local config flow. It safely merges the MCP entry and never appends instructions to a global rules file. See [Agent Setup](docs/AGENT-SETUP.md). ## What agents can do The server exposes 12 MCP tools: - Capture, search, list, fetch, update, and delete thoughts. - Link and traverse typed graph edges with `manage_edges`, `explore_graph`, and `expand_neighbors`. - Build trusted, token-bounded context with `get_brief` and `select_context`. - Audit the database with `thought_stats`. Search returns summaries and IDs so clients can fetch full content only when needed. Project-aware operations resolve scope from MCP roots and fail closed when the project cannot be identified. Untrusted or external memories are returned inside explicit data-only fences. The optional Forage and Onboard skills are packaged with supported clients. They run in the user's agent session; ShelbyMCP does not receive or store model credentials. Standalone prompt bodies remain available: ```bash shelby-mcp forage shelby-mcp onboard shelby-mcp migrate shelby-mcp protocol ``` ## HTTP and OAuth Start Streamable HTTP on port 3100: ```bash SHELBY_API_KEY="replace-with-a-long-random-secret" \ npx -y shelbymcp --transport http --host 127.0.0.1 --port 3100 ``` Endpoints include `/mcp`, `/health`, and MCP discovery documents. Setting `SHELBY_API_KEY` enables bearer authentication and an OAuth authorization-code flow with protected-resource discovery, S256 PKCE, dynamic client registration, and resource-bound access and refresh tokens. Tokens do not expire or rotate; rotate `SHELBY_API_KEY` to revoke them. Without it, HTTP runs unauthenticated and the OAuth endpoints return `503`; do not bind an unauthenticated server to an untrusted network. ## Build from source ```bash git clone https://github.com/Studio-Moser/shelbymcp.git cd shelbymcp cargo build -p shelby-mcp cargo test --workspace npm ci npm test ``` Rust owns the product. Node is used only for the small npm launcher, packaging scripts, and their tests. See [Development](docs/DEVELOPMENT.md) and [Architecture](docs/ARCHITECTURE.md). Memory-engine pull requests also run a deterministic contract and public retrieval gate. See [Memory evaluation](<docs/Memory Evaluation.md>). ## Reuse in Shelby App The workspace is intentionally layered for the cross-platform Shelby App: - `shelby-memory` is the SQLite memory engine and all memory-domain behavior. - `shelby-integrations` is the current client catalog plus safe setup/status/uninstall helpers. - `shelby-mcp` exposes the MCP service and reusable Axum router as a library as well as a binary. The app can embed these crates in-process, share one database contract across macOS and iOS, and host the same HTTP router without spawning Node. ## License MIT. See [LICENSE](LICENSE).