npm package: @justintabb/research-consensus-mcp
Description: MCP server that provides patent research consensus analysis using OpenAI and Gemini for identifying novel claims and patentable inventions
Author: Justin Tabb
Latest version: 1.0.2

# Research Consensus MCP Server

An MCP (Model Context Protocol) server that exposes a `research_consensus` tool, enabling Claude Code to query both OpenAI and Google Gemini for patent research analysis. The tool identifies novel claims, patentable inventions, and prior art considerations, presenting findings in formal patent terminology.

## Quick Start (Recommended)

Use directly with `npx` - no installation required:

```json
{
  "mcpServers": {
    "research-consensus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@justintabb/research-consensus-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here",
        "OPENAI_MODEL": "gpt-4o",
        "GEMINI_API_KEY": "your-gemini-key-here",
        "GEMINI_MODEL": "gemini-2.5-pro"
      }
    }
  }
}
```

Add this to your `.mcp.json` file (in your project or `~/.claude/`), replace the API keys, and restart Claude Code.

## Installation Options

### Option 1: npx (Recommended)

No installation needed. Just add the configuration above to your `.mcp.json`.

### Option 2: Global Install

```bash
npm install -g @justintabb/research-consensus-mcp
```

Then in `.mcp.json`:

```json
{
  "mcpServers": {
    "research-consensus": {
      "type": "stdio",
      "command": "research-consensus-mcp",
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here",
        "OPENAI_MODEL": "gpt-4o",
        "GEMINI_API_KEY": "your-gemini-key-here",
        "GEMINI_MODEL": "gemini-2.5-pro"
      }
    }
  }
}
```

### Option 3: Local Development

```bash
git clone https://github.com/justintabb/research-consensus-mcp
cd research-consensus-mcp
npm install
npm run build
```

Then in `.mcp.json`:

```json
{
  "mcpServers": {
    "research-consensus": {
      "command": "node",
      "args": ["/path/to/research-consensus-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here",
        "OPENAI_MODEL": "gpt-4o",
        "GEMINI_API_KEY": "your-gemini-key-here",
        "GEMINI_MODEL": "gemini-2.5-pro"
      }
    }
  }
}
```

## Configuration

### Required Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | Your OpenAI API key |
| `OPENAI_MODEL` | Model to use (e.g., `gpt-4o`, `gpt-4-turbo`) |

### Recommended for Consensus Mode

| Variable | Default | Description |
|----------|---------|-------------|
| `GEMINI_API_KEY` | - | Your Google Gemini API key (enables consensus mode) |
| `GEMINI_MODEL` | `gemini-2.5-pro` | Gemini model to use |

### Optional Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Custom API endpoint |
| `OPENAI_TIMEOUT_MS` | `1200000` | Request timeout in milliseconds |
| `OPENAI_MAX_OUTPUT_TOKENS` | `4096` | Maximum tokens in response |
| `OPENAI_TEMPERATURE` | `0.7` | Temperature setting (0-2) |
| `GEMINI_TIMEOUT_MS` | `1200000` | Gemini request timeout |
| `GEMINI_MAX_OUTPUT_TOKENS` | `8192` | Maximum Gemini tokens |
| `GEMINI_TEMPERATURE` | `0.7` | Gemini temperature setting |
| `RATE_LIMIT_MAX_CALLS` | `3` | Max API calls per window |
| `RATE_LIMIT_WINDOW_MS` | `60000` | Rate limit window in milliseconds |
| `DEBUG` | `false` | Include raw API response in output |

### Full Configuration Example

```json
{
  "mcpServers": {
    "research-consensus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@justintabb/research-consensus-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-key-here",
        "OPENAI_MODEL": "gpt-4o",
        "OPENAI_TIMEOUT_MS": "600000",
        "OPENAI_MAX_OUTPUT_TOKENS": "4096",
        "OPENAI_TEMPERATURE": "0.7",
        "GEMINI_API_KEY": "your-gemini-key-here",
        "GEMINI_MODEL": "gemini-2.5-pro",
        "RATE_LIMIT_MAX_CALLS": "5",
        "RATE_LIMIT_WINDOW_MS": "60000"
      }
    }
  }
}
```

## Tool Schema

### Tool Name

`research_consensus`

### Description

Patent Research Consensus Tool - Analyzes technical descriptions to identify novel claims, patentable inventions, and prior art considerations using multi-model consensus.

### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task` | string | Yes | The technical description or invention to analyze |
| `context` | string | No | Technical specifications, algorithms, system architecture, prior art references |
| `mode` | enum | No | Analysis mode (see below) |
| `constraints` | string | No | Specific patent requirements, jurisdictions, or claim limitations |
| `output_format` | enum | No | `plain`, `bullets`, or `json` |
| `json_schema` | object | No | Schema for structured JSON responses |
| `safety_notes` | string | No | Confidential information to exclude |
| `consensus` | boolean | No | Enable consensus mode (calls both OpenAI + Gemini) |
| `reasoning` | boolean | No | Enable reasoning mode (uses gpt-5.2-pro + gemini-2.5-pro). When false, uses faster models (gpt-5.2 + gemini-2.5-flash) |

### Analysis Modes

| Mode | Patent Research Application |
|------|----------------------------|
| `second_opinion` | General patentability assessment and novelty analysis (default) |
| `architecture_review` | Technical claim structure and dependent claim hierarchy |
| `edge_cases` | Prior art vulnerabilities and claim scope limitations |
| `security_review` | Trade secret considerations and disclosure risks |
| `debug` | Claim language precision and ambiguity analysis |
| `prompt_review` | Specification clarity and enablement review |

### Output

```json
{
  "consensus_mode": true,
  "both_succeeded": true,
  "openai_response": {
    "answer": "Patent analysis from OpenAI...",
    "model": "gpt-4o"
  },
  "gemini_response": {
    "answer": "Patent analysis from Gemini...",
    "model": "gemini-2.5-pro"
  },
  "guidance": "Compare both analyses for consensus on patentability..."
}
```

## Example Invocations

### Novel Claim Identification

```json
{
  "task": "Identify patentable claims in a machine learning system that uses federated learning with differential privacy to train models across distributed edge devices",
  "context": "The system implements a novel gradient compression algorithm that reduces communication overhead by 90% while maintaining model accuracy within 2% of centralized training. Key innovations include adaptive noise injection based on local data sensitivity metrics.",
  "mode": "second_opinion",
  "consensus": true,
  "output_format": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "novel_claims": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "claim_type": { "type": "string" },
            "claim_language": { "type": "string" },
            "novelty_basis": { "type": "string" }
          }
        }
      },
      "prior_art_risks": { "type": "array", "items": { "type": "string" } },
      "recommended_dependent_claims": { "type": "array", "items": { "type": "string" } }
    }
  }
}
```

### Prior Art Analysis

```json
{
  "task": "Analyze prior art risks for a real-time video compression algorithm",
  "context": "Algorithm uses temporal prediction with learned motion vectors from transformer architecture. Claims novelty in combining attention mechanisms with traditional codec pipelines for 40% bitrate reduction.",
  "mode": "edge_cases",
  "consensus": true,
  "output_format": "bullets"
}
```

### Claim Structure Review

```json
{
  "task": "Review claim hierarchy for a blockchain-based supply chain tracking system",
  "context": "Independent claims cover: (1) consensus mechanism using proof-of-provenance, (2) cryptographic attestation of physical goods via IoT sensors, (3) smart contract for automated compliance verification",
  "mode": "architecture_review",
  "constraints": "Must be defensible against Ethereum and Hyperledger prior art",
  "consensus": true
}
```

### Specification Enablement Review

```json
{
  "task": "Evaluate specification for enablement and written description requirements",
  "context": "[Full specification text including detailed algorithm descriptions, flowcharts, and example implementations]",
  "mode": "prompt_review",
  "constraints": "USPTO 35 U.S.C. 112(a) compliance required",
  "consensus": true
}
```

## Security Features

1. **Secret Redaction**: Automatically detects and redacts common secret patterns:
   - API keys (OpenAI, AWS, Stripe, GitHub, etc.)
   - Bearer tokens
   - Database connection strings
   - Private keys (PEM format)
   - Environment variable patterns
   - JWTs

2. **Rate Limiting**: In-memory sliding window rate limiter prevents excessive API usage.

3. **No Secret Logging**: API keys are never logged.

4. **Timeout Protection**: All requests have configurable timeouts.

## Troubleshooting

### Server won't start

1. Check that `OPENAI_API_KEY` and `OPENAI_MODEL` are set in your `.mcp.json`
2. Ensure Node.js >= 18 is installed
3. Try running manually: `npx -y @justintabb/research-consensus-mcp`

### Rate limit errors

Increase the limit or window in your `.mcp.json`:

```json
{
  "env": {
    "RATE_LIMIT_MAX_CALLS": "10",
    "RATE_LIMIT_WINDOW_MS": "60000"
  }
}
```

### Timeout errors

Increase the timeout:

```json
{
  "env": {
    "OPENAI_TIMEOUT_MS": "120000",
    "GEMINI_TIMEOUT_MS": "120000"
  }
}
```

## License

MIT