Physicist MCP Server
# Physicist Model Context Protocol (MCP) Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
A Model Context Protocol (MCP) server providing deep LLM-agent tool, resource, and prompt integrations with **[Physicist](https://github.com/leouofa/physicist)** — an open-source computational research platform and quantitative analytical laboratory for comparative particle physics, subatomic particles, and quantum state manifolds.
---
## Overview
The `physicist-mcp` server enables AI agents (Claude Code, Cursor, Gemini CLI, Antigravity) to query, manipulate, cluster, and synthesize physics domain models directly over standard input/output (`stdio`):
- **51 Registered MCP Tools** across 8 functional modules (Search, Particle Groups, Subatomic Particles, Quantum States, Clustering, Synthesis Reports, Background Jobs, and System Diagnostics).
- **4 Registered MCP Resources** exposing read-only live platform status, catalogs, cluster snapshots, and markdown monographs.
- **2 MCP Prompt Templates** for comparative particle physics studies and quantum cluster synthesis monographs.
- **1024-dimensional semantic manifold** querying via PostgreSQL `pgvector` HNSW indexes.
---
## Architectural Mapping
| Tier / Domain | Model | Table Name | MCP Module / Tools |
|---|---|---|---|
| **Tier 1** | Particle Groups / Families | `particle_groups` | `list_particle_groups`, `get_particle_group`, `create_particle_group`, `update_particle_group`, `delete_particle_group`, `upsert_particle_groups_batch`, `populate_particle_groups`, `populate_particle_group_subatomic_particles` |
| **Tier 2** | Subatomic Particles / Hadrons | `subatomic_particles` | `list_subatomic_particles`, `get_subatomic_particle`, `create_subatomic_particle`, `update_subatomic_particle`, `delete_subatomic_particle`, `upsert_subatomic_particles_batch`, `generate_subatomic_particle_embedding`, `populate_subatomic_particle_quantum_states`, `populate_subatomic_particles_bulk` |
| **Tier 3** | Quantum States / Eigenmodes | `quantum_states` | `list_quantum_states`, `get_quantum_state`, `create_quantum_state`, `update_quantum_state`, `delete_quantum_state`, `upsert_quantum_states_batch`, `generate_quantum_state_embedding`, `populate_quantum_states_bulk` |
| **Clustering** | 15-Level Agglomerative | `cluster_snapshots`, `cluster_groups` | `compute_clusters`, `create_cluster_snapshot`, `list_cluster_snapshots`, `get_cluster_snapshot`, `delete_cluster_snapshot`, `list_cluster_groups`, `get_cluster_group` |
| **Synthesis** | Multi-Stage Map-Reduce | `cluster_reports`, `cluster_report_summaries` | `list_cluster_reports`, `get_cluster_report`, `create_cluster_report`, `delete_cluster_report`, `generate_deep_synthesis`, `list_report_summaries`, `get_report_summary`, `list_report_sub_reports`, `get_report_sub_report` |
| **Global Search** | Cross-Catalog pgvector | Multi-table | `search`, `find_counterparts` |
| **Platform** | Jobs & System Info | Multi-service | `list_jobs`, `get_job_status`, `wait_for_job`, `get_platform_status`, `get_settings`, `update_context_window`, `trigger_bulk_embeddings`, `get_openapi_spec` |
---
## Installation & Setup
### Prerequisites
- Node.js 20+
- Running instance of [Physicist](https://github.com/leouofa/physicist) (`http://localhost:3000`)
### Build
```bash
git clone https://github.com/leouofa/physicist-mcp.git
cd physicist-mcp
npm install
npm run build
```
### Running the Server
```bash
# Run with defaults (http://localhost:3000/api/v1)
node dist/index.js
# Or with custom options
node dist/index.js --url http://localhost:3000/api/v1 --timeout 90000
```
---
## Configuration
Configuration options can be supplied via environment variables or CLI flags:
| Environment Variable | CLI Flag | Default | Description |
|---|---|---|---|
| `PHYSICIST_API_URL` | `-u`, `--url` | `http://localhost:3000/api/v1` | Base URL of Physicist REST API |
| `PHYSICIST_API_KEY` | `-k`, `--api-key` | *(none)* | Optional Bearer token for authentication |
| `PHYSICIST_TIMEOUT_MS` | `-t`, `--timeout` | `60000` | HTTP request timeout in milliseconds |
---
## MCP Host Integration
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"physicist": {
"command": "node",
"args": ["/path/to/physicist-mcp/dist/index.js"],
"env": {
"PHYSICIST_API_URL": "http://localhost:3000/api/v1"
}
}
}
}
```
### Antigravity (`~/.gemini/antigravity/mcp_config.json`)
```json
{
"mcpServers": {
"physicist": {
"command": "node",
"args": ["/Users/leonid/src/physicist-mcp/dist/index.js"],
"env": {
"PHYSICIST_API_URL": "http://localhost:3000/api/v1"
}
}
}
}
```
---
## Tool Catalog
### 1. Global Search & Manifolds
- `search`: Unified cross-catalog semantic (1024-d cosine similarity) or keyword search across subatomic particles and quantum states.
- `find_counterparts`: Find nearest physical counterparts or symmetry analogs using 1024-dimensional pgvector cosine distance.
### 2. Tier 1: Particle Groups
- `list_particle_groups`: List taxonomic families with particle counts.
- `get_particle_group`: Retrieve a particle group with nested subatomic particles.
- `create_particle_group`: Register a new particle group.
- `update_particle_group`: Update name or theoretical description.
- `delete_particle_group`: Cascade delete a particle group.
- `upsert_particle_groups_batch`: Bulk upsert particle groups by name.
- `populate_particle_groups`: Trigger LLM discovery of particle groups.
- `populate_particle_group_subatomic_particles`: Trigger LLM discovery of particles for a group.
### 3. Tier 2: Subatomic Particles
- `list_subatomic_particles`: Filter particles by group, themes, embedding status, and search keywords.
- `get_subatomic_particle`: Retrieve particle profile with vector embedding and child quantum states.
- `create_subatomic_particle`: Create a new subatomic particle.
- `update_subatomic_particle`: Update physical attributes or reassign particle group.
- `delete_subatomic_particle`: Cascade delete a particle.
- `upsert_subatomic_particles_batch`: Bulk upsert particles under a particle group.
- `generate_subatomic_particle_embedding`: Generate 1024-d pgvector embedding vector.
- `populate_subatomic_particle_quantum_states`: Trigger LLM discovery of quantum states for a particle.
- `populate_subatomic_particles_bulk`: Bulk discover particles across all groups.
### 4. Tier 3: Quantum States
- `list_quantum_states`: Filter quantum states and eigenmodes.
- `get_quantum_state`: Retrieve quantum state details and parent particle metadata.
- `create_quantum_state`: Create a new quantum state or eigenmode.
- `update_quantum_state`: Update quantum numbers or descriptions.
- `delete_quantum_state`: Delete a quantum state.
- `upsert_quantum_states_batch`: Bulk upsert quantum states under a particle.
- `generate_quantum_state_embedding`: Generate 1024-d vector embedding.
- `populate_quantum_states_bulk`: Bulk discover quantum states.
### 5. Clustering & Snapshots
- `compute_clusters`: Compute live connected-components vector clusters across 15 granularity levels without persisting.
- `create_cluster_snapshot`: Compute clustering and freeze it immediately into an immutable snapshot.
- `list_cluster_snapshots`: List frozen snapshots.
- `get_cluster_snapshot`: Retrieve snapshot with groups, members, and reports.
- `delete_cluster_snapshot`: Delete a cluster snapshot.
- `list_cluster_groups`: List archetype groups in a snapshot.
- `get_cluster_group`: Retrieve a single archetype cluster group with member entities.
### 6. Synthesis Reports
- `list_cluster_reports`: List multi-phase synthesis reports.
- `get_cluster_report`: Retrieve scholarly report content, progress, and intermediate summaries.
- `create_cluster_report`: Initiate a 2-Phase Map-Reduce synthesis monograph.
- `delete_cluster_report`: Delete a cluster report.
- `generate_deep_synthesis`: Upgrade or run a 3-Phase Hierarchical Deep Synthesis.
- `list_report_summaries`: List Phase 1 per-cluster summaries.
- `get_report_summary`: Retrieve a single Phase 1 summary.
- `list_report_sub_reports`: List Phase 2 batch syntheses.
- `get_report_sub_report`: Retrieve a single Phase 2 batch analysis.
### 7. Background Jobs
- `list_jobs`: List recent ActiveJob/Sidekiq background tasks.
- `get_job_status`: Inspect job status, progress, and results.
- `wait_for_job`: Poll a background task until completion or failure.
### 8. Platform & Diagnostics
- `get_platform_status`: Platform health, record counts, and LLM configuration.
- `get_settings`: Embedding completion metrics and LLM presets.
- `update_context_window`: Dynamically adjust LLM context window token size.
- `trigger_bulk_embeddings`: Enqueue bulk embedding calculations.
- `get_openapi_spec`: Retrieve OpenAPI 3.1 specification.
---
## MCP Resources
| URI | Format | Description |
|---|---|---|
| `physicist://status` | `application/json` | System health, entity counts, LLM models, and context window budgets. |
| `physicist://particle-groups` | `application/json` | Full catalog of particle groups and subatomic particle counts. |
| `physicist://snapshots/{id}` | `application/json` | Frozen cluster snapshot including discovered archetype groups and members. |
| `physicist://reports/{id}` | `text/markdown` | Full academic monograph generated by the synthesis pipeline. |
---
## MCP Prompts
- `comparative_particle_analysis`: Rigorous comparative particle physics analysis between two entities across particle groups using gauge invariants, spin-statistics, and semantic manifold distance.
- `quantum_cluster_monograph`: Academic monograph draft addressing a research inquiry grounded in a frozen snapshot's archetype clusters.
---
## Testing
```bash
# Run unit test suite
npm test
# Run tests in watch mode
npm run test:watch
```
---
## License
MIT License. Copyright (c) 2026 Leonid Medovyy.
TDQS
Scored across 51 tools
Many tools share the 'populate' verb with subtly different scopes (populate_particle_groups, populate_particle_group_subatomic_particles, populate_subatomic_particles_bulk, populate_subatomic_particle_quantum_states, populate_quantum_states_bulk), and generate_deep_synthesis vs create_cluster_report vs compute_clusters vs create_cluster_snapshot require careful reading to distinguish. Descriptions do disambiguate most cases, but an agent can easily pick the wrong populate/synthesis variant.
The dominant pattern is snake_case verb_noun (list_/get_/create_/update_/delete_/upsert_/populate_/generate_), applied consistently across resources. Minor deviations exist — bare 'search', 'find_counterparts', 'compute_clusters', and 'wait_for_job' — where verb style shifts, but overall the convention is predictable.
51 tools is heavy even for a multi-resource domain with particles, quantum states, groups, clustering, reports, jobs, and settings. Several capabilities could be folded into parameters (e.g. consolidating the five populate_* variants or the report summary/sub-report list/get pairs), and the sheer surface raises selection cost for an agent.
The surface covers full CRUD plus batch upserts for particle groups, subatomic particles, and quantum states, along with embeddings, clustering, report lifecycle, job polling, and platform settings. Gaps are minor: no job cancellation, no report update/regeneration, and snapshot lifecycle lacks an export/merge operation, but core workflows are covered.