# MCP Rust Documentation Server

This is a Model Context Protocol (MCP) server that provides comprehensive access to Rust crate documentation and metadata, offering essential context for LLMs when working with Rust code.

## Features

- **Documentation Lookup**: Fetches documentation for any Rust crate available on docs.rs
- **Crate Search**: Search for crates on crates.io with detailed results
- **Metadata Retrieval**: Get comprehensive metadata for specific crates
- **Pagination Support**: Handle large documentation with pagination
- **Error Handling**: Robust error handling with detailed logging
- **Session Tracking**: Session management for better debugging
- **Structured Responses**: Well-formatted, structured responses

## Architecture

The server follows a modular architecture inspired by AWS MCP server patterns:

```
mcp-rust-docs/
├── index.js          # Entry point (backward compatibility)
├── src/
│   ├── server.js      # Main server implementation with tools
│   ├── models.js      # Data models and validation schemas
│   └── utils.js       # Utility functions and API clients
├── package.json
└── README.md
```

## Tools Available

### 1. `lookup_crate_docs`
Fetches and returns documentation for a specific Rust crate from docs.rs.

**Parameters:**
- `crateName` (required): Name of the Rust crate
- `version` (optional): Specific version (defaults to 'latest')
- `maxLength` (optional): Maximum characters to return (default: 8000)
- `startIndex` (optional): Starting character index for pagination (default: 0)

**Example Usage:**
```javascript
// Basic lookup
lookup_crate_docs({ crateName: "tokio" })

// Specific version with pagination
lookup_crate_docs({ 
  crateName: "serde", 
  version: "1.0.0",
  maxLength: 5000,
  startIndex: 0 
})
```

### 2. `search_crates`
Search for Rust crates on crates.io with comprehensive results.

**Parameters:**
- `query` (required): Search query string
- `limit` (optional): Maximum results to return (1-50, default: 10)

**Example Usage:**
```javascript
search_crates({ query: "web framework", limit: 5 })
```

### 3. `get_crate_metadata`
Get detailed metadata for a specific Rust crate from crates.io.

**Parameters:**
- `crateName` (required): Name of the Rust crate

**Example Usage:**
```javascript
get_crate_metadata({ crateName: "axum" })
```

## Installation

```bash
# Clone the repository
git clone https://github.com/0xKoda/mcp-rust-docs.git
cd mcp-rust-docs

# Install dependencies
npm install
```

### Prerequisites

- Node.js >= 16.0.0
- npm

## Usage

```bash
# Start the server
npm start

# Development mode with debugging
npm run dev

# Run tests
npm test
```

## Integrating with AI Assistants

### Claude Desktop

Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "rust-docs": {
      "command": "node",
      "args": ["/absolute/path/to/index.js"]
    }
  }
}
```

### Amazon Q CLI

The server is compatible with Amazon Q CLI's MCP integration. Configure it in your Q CLI settings.

## Example Usage Scenarios

Once the server is running and configured with your AI assistant, you can ask questions like:

### Documentation Lookup
- "Look up the documentation for the 'tokio' crate"
- "Show me the documentation for 'serde' version 1.0.0"
- "Get the first 5000 characters of 'axum' documentation"

### Crate Search
- "Search for web framework crates"
- "Find crates related to async programming"
- "Show me the top 5 HTTP client crates"

### Metadata Queries
- "Get metadata for the 'reqwest' crate"
- "What's the latest version of 'clap'?"
- "Show me the download statistics for 'rand'"

### Advanced Queries
- "Compare the documentation of 'tokio' and 'async-std'"
- "What are the main features of the 'ratatui' crate?"
- "Find alternatives to the 'hyper' crate"

## Key Improvements Over Original

This implementation applies patterns from the AWS Documentation MCP Server:

### 1. **Modular Architecture**
- Separated concerns into models, utilities, and server logic
- Better maintainability and testability

### 2. **Enhanced Error Handling**
- Comprehensive error handling with detailed messages
- Proper HTTP status code handling
- Graceful degradation for network issues

### 3. **Multiple Tools**
- `lookup_crate_docs`: Documentation fetching
- `search_crates`: Crate discovery
- `get_crate_metadata`: Detailed crate information

### 4. **Better Validation**
- Strong input validation using Zod schemas
- Parameter bounds checking
- Type safety throughout

### 5. **Session Management**
- Session IDs for tracking and debugging
- Better logging with session context

### 6. **Pagination Support**
- Handle large documentation with `startIndex` and `maxLength`
- Continuation indicators for truncated content

### 7. **Structured Responses**
- Consistent response formatting
- Rich metadata in responses
- Better error reporting

## Testing with MCP Inspector

You can test this server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Then select "Connect to a local server" and follow the prompts.

## API Endpoints Used

- **docs.rs**: `https://docs.rs/{crate}/{version}/{crate}/index.html`
- **crates.io Search**: `https://crates.io/api/v1/crates?q={query}`
- **crates.io Metadata**: `https://crates.io/api/v1/crates/{crate}`

## Configuration

The server can be configured through environment variables:

- `RUST_DOCS_LOG_LEVEL`: Set logging level (default: 'info')
- `RUST_DOCS_MAX_CONTENT_LENGTH`: Maximum content length (default: 50000)
- `RUST_DOCS_REQUEST_TIMEOUT`: Request timeout in ms (default: 30000)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint
```

## License

MIT

## Changelog

### v2.0.0
- Complete rewrite with modular architecture
- Added crate search functionality
- Added metadata retrieval
- Enhanced error handling and logging
- Added pagination support
- Improved documentation and examples

### v1.0.0
- Initial release with basic documentation lookup