Content
# gemcp
MCP tools for RubyGems package intelligence. Ask about gems, versions, dependencies, and ownership. Get structured, provenance-tagged answers an agent can trust.
## Install
```bash
gem install gemcp
```
## MCP client config
Add to your MCP client (Claude Desktop, Kiro, etc.):
```json
{
"mcpServers": {
"gemcp": {
"command": "gemcp"
}
}
}
```
That's it. If your Ruby isn't on the default PATH, use the full path:
```json
{
"mcpServers": {
"gemcp": {
"command": "/path/to/gemcp"
}
}
}
```
Find it with `gem which gemcp && which gemcp`.
## What it does
`gemcp` reads from installed gemspecs first, a persistent disk cache second, and the RubyGems.org API only when neither has what you need.
## Tools
| Tool | Purpose |
|---|---|
| `search_gems` | Search installed gems first, then RubyGems.org |
| `get_gem` | Current gem metadata, preferring an installed gemspec |
| `list_gem_versions` | Installed versions first, registry versions otherwise |
| `get_gem_version` | Exact local version/platform first, API v2 otherwise |
| `get_gem_owners` | Public owner/maintainer data from RubyGems.org |
| `get_dependency_graph` | Bounded exploratory graph with constraints on edges |
| `get_gem_context` | Aggregated context: metadata + recent versions + owners |
| `check_compatibility` | Detect dependency conflicts between two gem versions |
| `get_releases_between` | List all releases between two versions of a gem |
| `reverse_dependencies` | Find gems that depend on a given gem |
| `compare_versions` | Diff dependency requirements between two versions |
## Example questions
These are the kinds of questions gemcp helps an agent answer with authoritative data:
- "Is sidekiq still actively maintained? Who owns it on RubyGems?"
- "What Ruby version does nokogiri 1.18.8 require?"
- "Can authlogic 3.6 coexist with Rails 8?"
- "What changed in authlogic's dependencies between version 3.6.1 and 6.6.0?"
- "What gems depend on rack?"
- "Show me every release of rails between 7.0.0 and 8.0.0"
- "Compare puma and unicorn — versions, owners, dependency counts"
- "What are the runtime dependencies of rails 8.1?"
- "Build me a dependency graph for sidekiq at depth 2"
- "Find me gems for background job processing"
## How it resolves data
```text
installed gemspecs
↓ miss
fresh disk cache
↓ stale/miss
conditional RubyGems.org request (ETag / If-Modified-Since)
↓
refresh cache
```
Local results include `metadata_source: "local"`. On network failure with a stale cache entry, the stale data is served rather than raising.
Search is conservative: when installed gems satisfy a query, no network call is made.
## Configuration
| Environment variable | Default | Meaning |
|---|---:|---|
| `GEMCP_LOCAL_FIRST` | `true` | Prefer installed gemspecs before network |
| `GEMCP_CACHE_DIR` | `~/.cache/gemcp` | Persistent JSON response cache |
| `GEMCP_CACHE_TTL` | `3600` | Cache freshness lifetime in seconds |
| `GEMCP_REQUESTS_PER_SECOND` | `2` | Outbound request rate limit |
| `RUBYGEMS_API_BASE_URL` | `https://rubygems.org` | API origin (useful for tests or mirrors) |
You can pass these through the MCP config:
```json
{
"mcpServers": {
"gemcp": {
"command": "gemcp",
"env": {
"GEMCP_LOCAL_FIRST": "true",
"GEMCP_CACHE_TTL": "7200"
}
}
}
}
```
## Architecture
Tools receive a `Client` via constructor injection. Each tool wraps its operation in `dry-monads` (`Success`/`Failure`) and renders the result to MCP response format. No global state.
```text
Tool.new(client:) → with_errors { client.do_thing } → Success(data) / Failure(error:, message:) → render → MCP response
```
The cache uses atomic temp-file + rename writes. The rate limiter uses a Mutex to serialize sleeps between outbound requests.
## Dependency graph limitations
`get_dependency_graph` is exploratory, not authoritative. It follows declared dependencies using the latest release of each, preserving requirement constraints on edges. It does not consider lockfiles, Ruby versions, platforms, or source configuration. It is not a substitute for Bundler.
## Compatibility checking limitations
`check_compatibility` tests whether two gems' declared dependency constraints overlap by sampling candidate versions against both `Gem::Requirement` objects. It catches common conflicts (e.g., `< 5.0` vs `= 8.0.0`) but is not a full constraint solver. It does not resolve transitive dependencies.
## Trust model
Registry facts (versions, checksums, dependencies, ownership, yanked state) are structured and authoritative. README, changelog, and documentation content is untrusted prose and never overrides registry facts.
## Dependencies
- [`fast-mcp`](https://github.com/yjacquin/fast-mcp) — MCP server framework (instance-based tools, Rack transport)
- [`dry-monads`](https://github.com/dry-rb/dry-monads) — `Success`/`Failure` result types for tool error handling
- `rack` — HTTP transport
## Development
```bash
git clone https://github.com/baweaver/gemcp.git
cd gemcp
bundle install
bundle exec rake
```
## License
MIT
MCP Store