# AGENT.md
Instructions for AI coding assistants working in this repository.
## Project Overview
This monorepo contains two packages for exploring Chromium and PDFium source code:
| Package | Directory | npm Name | Command |
|---------|-----------|----------|---------|
| **MCP Server** | `/` (root) | `chromium-codesearch-mcp` | Used by Claude Desktop |
| **CLI Tool** | `chromium-helper-cli/` | `chromium-helper` | `ch` or `chromium-helper` |
## First Message
If no concrete task is given, ask which package to work on:
- **MCP Server**: Read `src/index.ts` and `README.md`
- **CLI Tool**: Read `chromium-helper-cli/src/` and `chromium-helper-cli/README.md`
## Project Structure
```
chromium-helper/
├── src/index.ts # MCP server (single file, ~195KB)
├── package.json # MCP server package
├── chromium-helper-cli/ # CLI tool package
│ ├── src/
│ │ ├── index.ts # CLI entry point & commands
│ │ ├── api.ts # Chromium/Gerrit API client
│ │ ├── formatter.ts # Output formatting (plain/json/table)
│ │ ├── auth.ts # Gerrit authentication
│ │ ├── config.ts # Configuration management
│ │ ├── cookie-helper.ts # Cookie extraction helpers
│ │ └── ai-guide.ts # --ai flag documentation
│ └── package.json # CLI package
└── AGENT.md # This file
```
## Code Quality
- No `any` types unless absolutely necessary
- Check `node_modules` for external API type definitions instead of guessing
- Always use standard top-level imports, no dynamic imports
- Never remove or downgrade code to fix type errors; upgrade dependencies instead
- Ask before removing functionality that appears intentional
## Commands
### MCP Server (root directory)
```bash
npm run build # Build TypeScript
npm run dev # Watch mode
npm test # Run basic tests
npm start # Start server
```
### CLI Tool (chromium-helper-cli/)
```bash
cd chromium-helper-cli
npm run build # Build TypeScript
npm run dev # Watch mode
npm start # Run CLI
```
### After Code Changes
```bash
npm run build # Always rebuild after changes (get full output, no tail)
```
### Never Run
- `npm run dev` in background (use for interactive development only)
- Don't commit unless user asks
### Testing
```bash
# MCP Server
npm test
# CLI - manual testing
node dist/index.js search "LOG(INFO)" --limit 3
node dist/index.js gerrit status 6624568
```
## API Integration
Both packages use the same external APIs:
| API | Base URL | Purpose |
|-----|----------|---------|
| Chromium CodeSearch | `grimoireoss-pa.clients6.google.com` | Code search |
| Chromium Gerrit | `chromium-review.googlesource.com` | CLs, reviews |
| PDFium Gerrit | `pdfium-review.googlesource.com` | PDFium CLs |
| Issue Tracker | `issues.chromium.org` | Bug tracking |
| LUCI | `cr-buildbucket.appspot.com` | Build results |
## Key Patterns
### MCP Server (src/index.ts)
- Single-file architecture with all tools defined inline
- Uses `@modelcontextprotocol/sdk` for MCP protocol
- Each tool is registered with `server.setRequestHandler`
- Returns structured data for AI consumption
### CLI Tool (chromium-helper-cli/src/)
- Uses `commander` for CLI parsing
- `api.ts` contains all API functions (shared logic)
- `formatter.ts` handles output formatting
- Three output formats: `plain`, `json`, `table`
## Adding New Features
### Adding a new MCP Tool
1. Add tool definition to `src/index.ts`
2. Register handler with `server.setRequestHandler`
3. Update README.md with tool documentation
### Adding a new CLI Command
1. Add command in `chromium-helper-cli/src/index.ts`
2. Add API function in `chromium-helper-cli/src/api.ts`
3. Add formatter in `chromium-helper-cli/src/formatter.ts`
4. Update `chromium-helper-cli/README.md`
5. Update AI guide in `chromium-helper-cli/src/ai-guide.ts`
## GitHub Issues
### When reading issues
- Always read all comments on the issue
### When creating issues
- Add labels: `mcp`, `cli`, `bug`, `enhancement`
- Be specific about which package is affected
### When closing via commit
- Use `fixes #<number>` or `closes #<number>` in commit message
## Changelog
**Location**: `CHANGELOG.md` (root only, covers both packages)
### Format
```markdown
## [Unreleased]
### Breaking Changes
### Added
### Changed
### Fixed
### Removed
```
### Rules
- Read full `[Unreleased]` section before adding entries
- New entries always go under `## [Unreleased]`
- Append to existing subsections, don't create duplicates
- Never modify released version sections
## Style
- Keep answers short and concise
- No emojis in commits, issues, or code
- No fluff or cheerful filler text
- Technical prose only, be kind but direct
## Shell Commands
- Always use `-v` flag when running `rm` to show deleted files
## Git Commands
- Never run `git add -A`
- Add files explicitly: `git add <specific-files>`
- Or use targeted commands: `git add -p`
## Common Tasks
### Check CL status (testing the tools)
```bash
# CLI
cd chromium-helper-cli && node dist/index.js gerrit status 6624568
# MCP (requires MCP client)
# Test with test-mcp.js
```
### Search Chromium code
```bash
cd chromium-helper-cli && node dist/index.js search "WebContents" --limit 5
```
### Debug API responses
Both packages log to stderr when issues occur. Check API response structure if results are unexpected.
## Release Process
1. Update `CHANGELOG.md` with all changes under `[Unreleased]`
2. Bump version in relevant `package.json`:
- Root for MCP server
- `chromium-helper-cli/package.json` for CLI
3. Build and test both packages
4. Commit and tag
5. Publish to npm:
```bash
# MCP Server
npm publish
# CLI
cd chromium-helper-cli && npm publish
```
