# ZRead MCP Server Integration

This document describes the integration of ZRead MCP server into the GLAM project.

## Overview

ZRead is a remote MCP server that provides tools for exploring GitHub repositories:
- **search_doc**: Search documentation, code, and comments
- **get_repo_structure**: Get repository structure and file list
- **read_file**: Read the complete code content of specified files

## Configuration

### 1. Get API Key

Visit https://z.ai/manage-apikey/apikey-list to obtain your Z.AI API key.

### 2. Configure OpenCode

The MCP server is configured in `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "zread": {
      "type": "remote",
      "url": "https://api.z.ai/api/mcp/zread/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}
```

Replace `YOUR_API_KEY_HERE` with your actual Z.AI API key from step 1.

**Note:** The same API key works for both `zread` and `web-reader` MCP servers.

## Usage

Once configured, ZRead tools will be available in OpenCode sessions:

```
# Search GitHub repository documentation
Use zread search_doc to search for "React hooks" in "facebook/react" repository

# Get repository structure
Use zread get_repo_structure to view the file structure of "facebook/react"

# Read a specific file
Use zread read_file to read the contents of "facebook/react/packages/react/src/React.js"
```

## Troubleshooting

### Invalid access token error

If you receive an invalid access token error:
1. Verify the token was copied correctly from https://z.ai/manage-apikey/apikey-list
2. Check that the token is activated
3. Ensure the token has sufficient balance
4. Confirm the API key is correctly set in `~/.config/opencode/opencode.json`

### Connection timeout

If the connection to the MCP server times out:
1. Check your network connection
2. Verify firewall settings
3. Ensure the server URL is correct: https://api.z.ai/api/mcp/zread/mcp

### Repository access failed

If you are unable to search or read a repository:
1. Confirm the repository exists and is public (open source)
2. Check if the repository name is spelled correctly (format: owner/repo)
3. Visit https://zread.ai to search if this open source repository is supported

## Quota

Z.AI offers different plans with varying quotas for MCP calls:
- **Lite**: 100 web searches, web readers, and ZRead MCP calls
- **Pro**: 1,000 web searches, web readers, and ZRead MCP calls
- **Max**: 4,000 web searches, web readers, and ZRead MCP calls

All plans include a 5-hour maximum prompt resource pool for vision understanding.

## Documentation

- [ZRead MCP Server Documentation](https://docs.z.ai/devpack/mcp/zread-mcp-server)
- [OpenCode MCP Configuration](https://opencode.ai/docs/mcp-servers)
- [Model Context Protocol](https://modelcontextprotocol.io/)