# CodeWiki MCP Server

An MCP (Model Context Protocol) server that integrates with Google CodeWiki to fetch and cache documentation for GitHub repositories.

## Features

- **Repository Search**: Search for GitHub repositories on Google CodeWiki
- **Documentation Fetching**: Retrieve and parse documentation from CodeWiki
- **Smart Caching**: Cache documentation with TTL (Time To Live) to avoid repeated requests
- **Documentation Search**: Search within cached documentation for specific content
- **Cache Management**: List, clear, and manage cached repositories

## Installation

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the project:
   ```bash
   npm run build
   ```

## Setup

### VS Code Integration

The project includes VS Code MCP configuration. The `.vscode/mcp.json` file is automatically created during setup and configures the server for use with MCP-compatible clients.

### Git Configuration

A comprehensive `.gitignore` file is included to exclude:
- Build outputs (`dist/`, `build/`)
- Cache directories (`.codewiki-cache/`)
- Environment files (`.env*`)
- IDE files (`.vscode/`, `.idea/`)
- OS files (`.DS_Store`, `Thumbs.db`)
- Logs and temporary files

## Usage

### As an MCP Server

This server can be used with any MCP-compatible client. The server provides the following tools:

#### `search_repository`
Search for GitHub repositories on Google CodeWiki.

**Parameters:**
- `query` (string): Search query for repository name or owner/repo format

**Example:**
```json
{
  "query": "facebook/react"
}
```

#### `get_repository_docs`
Get documentation for a specific GitHub repository.

**Parameters:**
- `owner` (string): Repository owner/organization
- `repo` (string): Repository name
- `force_refresh` (boolean, optional): Force refresh cached documentation (default: false)

**Example:**
```json
{
  "owner": "facebook",
  "repo": "react",
  "force_refresh": false
}
```

#### `search_documentation`
Search within cached documentation for a repository.

**Parameters:**
- `owner` (string): Repository owner/organization
- `repo` (string): Repository name
- `query` (string): Search query within the documentation

**Example:**
```json
{
  "owner": "facebook",
  "repo": "react",
  "query": "hooks"
}
```

#### `list_cached_repositories`
List all repositories currently cached.

**Parameters:** None

#### `clear_cache`
Clear the documentation cache.

**Parameters:**
- `owner` (string, optional): Specific repository owner to clear
- `repo` (string, optional): Repository name when clearing specific repo

**Examples:**
```json
{
  "owner": "facebook",
  "repo": "react"
}
```

```json
{}
```

### Direct Usage

You can also run the server directly:

```bash
npm start
```

## Configuration

### Cache Settings

The cache manager supports the following configuration:

- **Default TTL**: 24 hours (configurable)
- **Cache Directory**: `.codewiki-cache` in the project root
- **Memory Cache**: In-memory cache for frequently accessed data
- **Disk Cache**: Persistent cache stored as JSON files

### Environment Variables

- `CODEWIKI_CACHE_DIR`: Custom cache directory path
- `CODEWIKI_CACHE_TTL`: Cache TTL in milliseconds (default: 86400000)

## Project Structure

```
codewiki-mcp-server/
├── src/
│   ├── server.ts           # Main MCP server implementation
│   ├── codewiki-client.ts  # Client for interacting with Google CodeWiki
│   └── cache-manager.ts    # Manages caching of documentation
├── .vscode/
│   └── mcp.json           # MCP server configuration for VS Code
├── .gitignore             # Git ignore rules
├── LICENSE                # MIT License
├── README.md              # This file
├── mcp.json              # MCP server manifest
├── package.json          # Project dependencies and scripts
└── tsconfig.json         # TypeScript configuration
```

## Architecture

### Components

1. **Server** (`server.ts`): Main MCP server implementation
2. **CodeWikiClient** (`codewiki-client.ts`): Client for interacting with Google CodeWiki
3. **CacheManager** (`cache-manager.ts`): Manages caching of documentation

### Data Flow

1. Client requests repository documentation
2. Server checks cache for existing data
3. If not cached or expired, fetches from Google CodeWiki
4. Parses and structures the documentation
5. Stores in cache for future requests
6. Returns structured documentation to client

## Development

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Cleaning

```bash
npm run clean
```

## Limitations

- **No Public API**: Google CodeWiki doesn't provide a public API, so this server uses web scraping
- **Rate Limiting**: Be respectful of CodeWiki's servers with appropriate delays
- **Repository Coverage**: Not all repositories may have CodeWiki documentation available
- **Content Parsing**: HTML structure changes on CodeWiki may require updates to the parsing logic

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Author

Chris Bunting <cbuntingde@gmail.com>