# Uspto Enriched Citation Mcp

> High-performance MCP server for USPTO Enriched Citation API v3 with AI-powered data extraction, token-saving context reduction, progressive disclosure workflows, and seamless cross-MCP integration

- **Type:** MCP server
- **Install:** `agentstack add mcp-john-walkoe-uspto-enriched-citation-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [john-walkoe](https://agentstack.voostack.com/s/john-walkoe)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [john-walkoe](https://github.com/john-walkoe)
- **Source:** https://github.com/john-walkoe/uspto_enriched_citation_mcp

## Install

```sh
agentstack add mcp-john-walkoe-uspto-enriched-citation-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# USPTO Patent Citation MCP Server (Enriched v3 + OA v2)

A high-performance Model Context Protocol (MCP) server providing access to **two USPTO patent citation APIs** — the **Enriched Citations v3** (AI-extracted passage locations, claim mapping) and the **Office Action Citations v2** (raw Form 892/1449 citation data) — with **token-saving context reduction** (90-95%), **progressive disclosure workflows**, **interactive MCP Apps UI panels**, and **seamless cross-MCP integration** for complete patent lifecycle analysis.

[]()
[]()
[]()
[]()
[]()
[](LICENSE)

## Demo

A single prompt drives a full examiner citation analysis — Enriched Citations MCP and Patent File Wrapper MCP working together to profile examiner citation patterns across both the enriched and raw OA datasets, with ultra-minimal field selection to keep token usage lean. Ultra-minimal mode requests only the fields needed for each step, so in the video you'll see many fields showing as — (not requested). That's intentional, not missing data.

https://github.com/user-attachments/assets/668bd241-5d98-4932-90b3-129c28084bc6

## 📚 Documentation

| Document | Description |
|----------|-------------|
| **[📥 Installation Guide](INSTALL.md)** | Complete cross-platform setup with automated scripts |
| **[🔑 API Key Guide](API_KEY_GUIDE.md)** | Step-by-step guide with screenshots for obtaining USPTO and Mistral API keys |
| **[📖 Usage Examples](USAGE_EXAMPLES.md)** | Function examples, workflows, and integration patterns |
| **[🎯 Prompt Templates](PROMPTS.md)** | Detailed guide to sophisticated prompt templates for citation analysis & research workflows |
| **[🧪 Testing Guide](tests/README.md)** | Test suite documentation and API key setup |
| **[🔒 Security Guidelines](SECURITY_GUIDELINES.md)** | Comprehensive security best practices |
| **[🛡️ Security Scanning](SECURITY_SCANNING.md)** | Automated secret detection and prevention guide |
| **[⚖️ License](LICENSE)** | MIT License terms and conditions |

## ⚡ Quick Start

### Windows Install

**Run PowerShell as Administrator**, then:

```powershell
# Navigate to your user profile
cd $env:USERPROFILE

# If git is installed:
git clone https://github.com/john-walkoe/uspto_enriched_citation_mcp.git
cd uspto_enriched_citation_mcp

# If git is NOT installed:
# Download and extract the repository to C:\Users\YOUR_USERNAME\uspto_enriched_citation_mcp
# Then navigate to the folder:
# cd C:\Users\YOUR_USERNAME\uspto_enriched_citation_mcp

# Run setup script (sets execution policy for this session only):
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
.\deploy\windows_setup.ps1

# View INSTALL.md for sample script output.
# Close PowerShell Window.
# If you chose option to "configure Claude Desktop integration" then restart Claude Desktop
```

The PowerShell script will:

- ✅ Check for and auto-install uv (via winget or PowerShell script)
- ✅ Install dependencies and create executable
- ✅ Prompt for USPTO API key (required) or Detect if you had installed the developer's other USPTO MCPs and ask if want to use existing keys from those installation.
- 🔒 **If entering in API keys, the script will automatically store API keys securely using Windows DPAPI encryption**
- ✅ Ask if you want Claude Desktop integration configured
- 🔒 **Offer secure configuration method (recommended) or traditional method (API keys in plain text in the MCP JSON file)**
- ✅ Backups and then automatically merge with existing Claude Desktop config (preserves other MCP servers)
- ✅ Provide installation summary and next steps

### Claude Desktop Configuration - Manual installs

```json
{
  "mcpServers": {
    "uspto_enriched_citations": {
      "command": "uv",
      "args": ["--directory", "C:/Users/YOUR_USERNAME/uspto_enriched_citation_mcp",
               "run",
               "uspto_enriched_citation_mcp"
      ],
      "env": {
        "USPTO_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}
```

**For detailed installation, manual setup, and troubleshooting**, see **[INSTALL.md](./INSTALL.md)**

## 🔑 Key Benefits

- **🗺️Smart Field Mapping & Selection** - User-configurable field sets via YAML without code changes
- **📊Progressive Disclosure Workflow** - Minimal discovery → Balanced analysis → Detailed citation examination
- **🎯Token-Saving Context Reduction** - 90-95% reduction to optimized search results
- **📋Lucene Query Syntax Support** - Full Apache Lucene Query Parser Syntax with validation
- **✨Two Citation APIs** - Enriched Citations v3 (AI-extracted) + Office Action Citations v2 (raw 892/1449)
- **🖥️MCP Apps UI** - Interactive card-based panels for citation results, OA citations, and statistics
- **🔗Cross-MCP Integration** - Links to Patent File Wrapper, PTAB, and other USPTO MCPs
- **🌐HTTP + stdio Dual Transport** - stdio for Claude Desktop, HTTP mode for MCP Apps and reverse proxies
- **🛡️Production-Ready Resilience** - Structured logging, retry logic, circuit breaker, rate limiting

### Workflow Design - All Performed by LLM with Minimal User Guidance

**User Requests the following:**

- *"Find all citations for application 16751234 and analyze the citation patterns"*
- *"Show me citations from Apple Inc in technology center 2100"*
- *"Research examiner citation patterns for art unit 2854"*
- *"Analyze citation decision types for machine learning patents filed in 2023"*
- *"Find citations that were CITED (not DISCARDED) in software classification 706"*

**LLM Performs these steps:**

**Step 1: Discovery minimal** → **Step 2: Filter & Select** → **Step 3: Analyze (optional)** → **Step 4: Citation Details (optional)** → **Step 5: Cross-MCP Integration (optional)**

The field configuration supports an optimized research progression:

1. **Discovery minimal** returns 50-100 citations efficiently with essential identifiers and decision info
2. **Filter & Select** from results to identify most relevant citations for detailed analysis
3. **Analyze (optional)** detailed research using balanced field set when comprehensive analysis needed
4. **Citation Details (optional)** get complete citation record with optional citing context and passage analysis
5. **Cross-MCP Integration (optional)** connect citations to prosecution history, PTAB challenges, or knowledge base research

## 🎯 Prompt Templates

The Citations MCP provides **5 guided workflow prompts** accessible directly in Claude Desktop UI. These templates automate complex multi-step citation analysis workflows and eliminate the need to memorize tool syntax.

**For detailed prompt documentation, usage examples, and cross-MCP integration patterns, see [PROMPTS.md](PROMPTS.md).**

### Core Prompt Workflows

| Prompt Name | Purpose |
|-------------|---------|
| `patent_citation_analysis` | Complete citation analysis for specific patents with prosecution context |
| `enhanced_examiner_behavior_intelligence_PFW_PTAB_FPD` | Comprehensive examiner profiling with citations, petitions, PTAB correlation |
| `litigation_citation_research_PFW_PTAB` | Complete litigation research package with prosecution & PTAB analysis |
| `technology_citation_landscape_PFW` | Map prior art landscape for technology areas |
| `art_unit_citation_assessment` | Analyze art unit citation norms and examiner patterns |

**Key Features Across All Templates:**

- **Enhanced Input Processing** - Flexible identifier support (patent numbers, application numbers, title keywords)
- **Smart Validation** - Automatic format detection and guidance
- **Cross-MCP Integration** - Seamless workflows with PTAB, FPD, Citations, and Pinecone MCPs

## 📊 Available Functions (10 Tools)

### Enriched Citations v3 Tools (AI-extracted passage locations, claim mapping)

| Tool | Use Case | Requirements |
|------|----------|--------------|
| `search_citations_minimal` | Ultra-fast citation discovery — 8 essential fields, 90-95% context reduction | USPTO_API_KEY |
| `search_citations_balanced` | Comprehensive citation analysis — 19 fields, 80-85% context reduction | USPTO_API_KEY |
| `get_citation_details` | Full single citation record by ID. **⚠️ Metadata only — use PFW for actual documents** | USPTO_API_KEY |
| `get_citation_statistics` | Database statistics and aggregations for strategic planning | USPTO_API_KEY |
| `get_available_fields` | Discover Enriched Citations field names and query syntax | None |

### Office Action Citations v2 Tools (raw Form 892/1449 data — broader coverage)

| Tool | Use Case | Requirements |
|------|----------|--------------|
| `search_oa_citations_minimal` | High-volume OA citation discovery — 7 key fields | USPTO_API_KEY |
| `search_oa_citations_balanced` | Detailed OA citation analysis — all 16 fields | USPTO_API_KEY |
| `get_oa_citation_fields` | Discover OA Citations field names and query syntax | None |

### Utility Tools

| Tool | Purpose | Requirements |
|------|---------|--------------|
| `validate_query` | Validate Lucene syntax and get optimization suggestions | None |
| `citations_get_guidance` | Context-efficient selective guidance sections | None |

**When to use each API:**
- **Enriched Citations v3**: When you need passage locations, claim mapping, quality scores, or AI-extracted analysis. Coverage from 2017-10-01.
- **OA Citations v2**: When you need broader coverage, raw Form 892/1449 data, or want to cross-check enriched results. Recommended as a secondary verification source.

**Detailed Citation Tier (`get_citation_details`)**: Single citation deep dive

- **Complete record**: All available citation metadata with formatted presentation
- **Optional context**: Include citing application details and passage-level analysis
- **Strategic insights**: Decision reasoning, relevance scores, relationship mapping

### LLM Guidance Function

| Function (Display Name) | Purpose | Requirements |
|----------|---------|------------|
| `citations_get_guidance` | Context-efficient selective guidance sections | None |

#### Context-Efficient Guidance System

**`citations_get_guidance` Tool** - Solves MCP Resources visibility problem with selective guidance sections:

🎯 **Quick Reference Chart** - Know exactly which section to call:

- 🔍 "Find citations by examiner/application/tech" → fields
-  📄 "Understand citation categories (X/Y/NPL)" → citation_codes
-  🔖 "Citation data coverage (2017+)" → data_coverage
-  🤝 "PFW workflow for office action documents" → workflows_pfw
-  🚩 "PTAB citation correlation" → workflows_ptab
-  📊 "FPD petition citation patterns" → workflows_fpd
-  🏢 "Complete lifecycle analysis" → workflows_complete
-  ⚙️ "Tool guidance and parameters" → tools
-  ❌ "Search errors or query issues" → errors
-  💰 "Reduce API costs and optimize" → cost

**Patent Attorney Workflows:**

- **Due Diligence**: Citation risk assessment and portfolio analysis
- **Prior Art Investigation**: Patentability research and invalidity analysis
- **Prosecution Strategy**: Examiner pattern analysis and response tactics
- **Competitive Intelligence**: Technology landscape and market positioning

**Cross-MCP Integration Workflows:**
- **PFW + Citations**: Connect citations to prosecution history for context
- **PTAB + Citations**: Correlate citation outcomes with challenge success rates
- **FPD + Citations**: Petition red flags and prosecution quality assessment
- **Complete Lifecycle Analysis**: PFW → Citations → PTAB → FPD integrated workflows
- **Knowledge Base Research**: Integrate with Pinecone Assistant for MPEP guidance

**Cost Optimization Guidance:**
- Start with minimal discovery to identify key citations
- Progress to balanced analysis only for strategically important citations
- Use ultra-minimal mode with custom fields parameter for 99% token reduction
- Validate complex queries before execution to avoid API waste
- Leverage cross-MCP integration to prevent duplicate research

The tool provides specific workflows, field recommendations, API call optimization strategies, and cross-MCP integration patterns for maximum efficiency. See **[USAGE_EXAMPLES.md](USAGE_EXAMPLES.md)** for detailed examples and integration workflows.

## 🔧 Field Customization

### User-Configurable Field Sets

The MCP server supports user-customizable field sets through YAML configuration at the project root. You can modify field sets that minimal and balanced searches bring back without changing any code!

**Configuration file:** `field_configs.yaml` (in project root)

### Easy Customization Process

1. **Open** `field_configs.yaml` in the project root directory
2. **Uncomment fields** you want by removing the `#` symbol
3. **Save the file** - changes take effect on next Claude Desktop restart
4. **Use the simplified tools** with your custom field selections

### Available Field Sets (Progressive Workflow)

- **`citations_minimal`** - Ultra-minimal for citation discovery: **8 essential fields** for high-volume discovery (50-100 results)
- **`citations_balanced`** - Comprehensive citation analysis: **18 key fields** for detailed citation analysis and portfolio research

### Professional Field Categories Available

**⚠️ API v3 Field Reality (22 total fields as of 2024-07-11)**

- **Core Identifiers**: `citedDocumentIdentifier`, `patentApplicationNumber`, `publicationNumber`, `id`
- **Citation Metadata**: `citationCategoryCode` (X=anticipates/obviates alone, Y=obviates combined — only X and Y in dataset, per WIPO ST.14), `examinerCitedReferenceIndicator`, `applicantCitedExaminerReferenceIndicator`
- **Organizational**: `groupArtUnitNumber`, `techCenter`, `workGroupNumber`
- **Temporal**: `officeActionDate`, `createDateTime`
- **Content**: `passageLocationText`, `relatedClaimNumberText`, `qualitySummaryText`, `officeActionCategory`
- **Reference Details**: `inventorNameText`, `kindCode`, `countryCode`, `nplIndicator` (boolean — X/Y records can be NPL)
- **System**: `createUserIdentifier`, `obsoleteDocumentIdentifier`

**❌ Fields NOT Available (despite code references):**
- `examinerNameText`, `firstApplicantName`, `decisionTypeCode`, `decisionTypeCodeDescriptionText`
- `inventionTitle`, `uspcClassification`, `cpcClassificationBag`, `patentStatusCodeDescriptionText`
- For examiner analysis: Use PFW MCP → get application numbers → search citations

### Example Customization

**File: `field_configs.yaml`**
```yaml
predefined_sets:
  citations_minimal:
    description: "Essential fields for citation discovery (90-95% context reduction)"
    fields:
      # === CROSS-MCP INTEGRATION FIELDS ===
      - patentApplicationNumber               # → Patent File Wrapper MCP
      - publicationNumber                     # → PTAB MCP (if granted)
      - groupArtUnitNumber                   # → All USPTO MCPs

      # === CITATION CORE FIELDS ===
      - citedDocumentIdentifier              # Citation reference
      - citationCategoryCode                 # X=US patent, Y=foreign, NPL=non-patent literature
      - techCenter                          # Technology classification
      - officeActionDate                    # Temporal analysis
      - examinerCitedReferenceIndicator      # Examiner vs Applicant
```

## 🔗 Lucene Query Syntax Guide

### Advanced Query Examples

**Field-Specific Searches:**
```sql
patentApplicationNumber:18010777                    # Exact application match
groupArtUnitNumber:1759                               # Art unit search
techCenter:2100                                       # Technology center match
inventorNameText:Smith*                               # Inventor name prefix wildcard
```

**Boolean Logic:**
```sql
techCenter:2100 AND groupArtUnitNumber:2854           # Boolean AND
citationCategoryCode:X OR citationCategoryCode:Y      # Only X and Y are populated in this dataset
techCenter:2100 NOT groupArtUnitNumber:1600          # Boolean NOT
```

**Range and Wildcard:**
```sql
officeActionDate:[2023-01-01 TO 2023-12-31]         # Date range
patentApplicationNumber:18*                           # Wildcard application search
citedDocumentIdentifier:US*

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [john-walkoe](https://github.com/john-walkoe)
- **Source:** [john-walkoe/uspto_enriched_citation_mcp](https://github.com/john-walkoe/uspto_enriched_citation_mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-john-walkoe-uspto-enriched-citation-mcp
- Seller: https://agentstack.voostack.com/s/john-walkoe
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.