API Reference

FastMCP server factory, payload models, and MCP helpers.

Payload models

class agentgrep.mcp.AgentGrepModel
class
class
class agentgrep.mcp.AgentGrepModel

Bases: BaseModel

Base model for MCP payloads.

model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
class agentgrep.mcp.SearchRecordModel
class
class
class agentgrep.mcp.SearchRecordModel

Bases: AgentGrepModel

Normalized search result payload.

schema_version: str
attribute
attribute
schema_version: str
ref: str
attribute
attribute
ref: str
kind: t.Literal['prompt', 'history']
attribute
attribute
kind: t.Literal['prompt', 'history']
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store: str
attribute
attribute
store: str
adapter_id: str
attribute
attribute
adapter_id: str
path: str
attribute
attribute
path: str
text: str
attribute
attribute
text: str
title: str | None
attribute
attribute
title: str | None
role: str | None
attribute
attribute
role: str | None
timestamp: str | None
attribute
attribute
timestamp: str | None
model: str | None
attribute
attribute
model: str | None
session_id: str | None
attribute
attribute
session_id: str | None
conversation_id: str | None
attribute
attribute
conversation_id: str | None
origin: RecordOriginModel | None
attribute
attribute
origin: RecordOriginModel | None
metadata: dict[str, t.Any]
attribute
attribute
metadata: dict[str, t.Any]
classmethod from_record(record)
classmethod method
classmethod method
classmethod from_record(record)

Build a typed result from an agentgrep search record.

Parameters:

record (SearchRecordLike)

Return type:

SearchRecordModel

_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.RecordOriginModel
class
class
class agentgrep.mcp.RecordOriginModel

Bases: AgentGrepModel

Project/workspace origin attached to a search result.

cwd: str | None
attribute
attribute
cwd: str | None
repo: str | None
attribute
attribute
repo: str | None
worktree: str | None
attribute
attribute
worktree: str | None
branch: str | None
attribute
attribute
branch: str | None
remote: str | None
attribute
attribute
remote: str | None
cwd_hash: str | None
attribute
attribute
cwd_hash: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.FindRecordModel
class
class
class agentgrep.mcp.FindRecordModel

Bases: AgentGrepModel

Normalized find result payload.

schema_version: str
attribute
attribute
schema_version: str
ref: str
attribute
attribute
ref: str
kind: t.Literal['find']
attribute
attribute
kind: t.Literal['find']
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store: str
attribute
attribute
store: str
adapter_id: str
attribute
attribute
adapter_id: str
path: str
attribute
attribute
path: str
path_kind: t.Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
attribute
attribute
path_kind: t.Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
metadata: dict[str, t.Any]
attribute
attribute
metadata: dict[str, t.Any]
classmethod from_record(record)
classmethod method
classmethod method
classmethod from_record(record)

Build a typed result from an agentgrep find record.

Parameters:

record (FindRecordLike)

Return type:

FindRecordModel

_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.SourceRecordModel
class
class
class agentgrep.mcp.SourceRecordModel

Bases: AgentGrepModel

Discovered source summary payload.

schema_version: str
attribute
attribute
schema_version: str
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store: str
attribute
attribute
store: str
adapter_id: str
attribute
attribute
adapter_id: str
path: str
attribute
attribute
path: str
path_kind: t.Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
attribute
attribute
path_kind: t.Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
source_kind: t.Literal['json', 'jsonl', 'sqlite', 'text', 'opaque']
attribute
attribute
source_kind: t.Literal['json', 'jsonl', 'sqlite', 'text', 'opaque']
coverage: t.Literal['default_search', 'inspectable', 'catalog_only', 'private']
attribute
attribute
coverage: t.Literal['default_search', 'inspectable', 'catalog_only', 'private']
searchable: bool
attribute
attribute
searchable: bool
search_by_default: bool
attribute
attribute
search_by_default: bool
searchable_reason: str
attribute
attribute
searchable_reason: str
inspectable: bool
attribute
attribute
inspectable: bool
version_detection: SourceVersionDetectionModel | None
attribute
attribute
version_detection: SourceVersionDetectionModel | None
search_root: str | None
attribute
attribute
search_root: str | None
mtime_ns: int
attribute
attribute
mtime_ns: int
classmethod from_source(source)
classmethod method
classmethod method
classmethod from_source(source)

Build a typed result from a discovered source.

Parameters:

source (SourceHandleLike)

Return type:

SourceRecordModel

_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.SourceVersionDetectionModel
class
class
class agentgrep.mcp.SourceVersionDetectionModel

Bases: AgentGrepModel

Detected version metadata for one discovered source.

app_version: str | None
attribute
attribute
app_version: str | None
data_version: str | None
attribute
attribute
data_version: str | None
strategy: t.Literal['version_check', 'embedded_metadata', 'shape_inference', 'catalog_observation']
attribute
attribute
strategy: t.Literal['version_check', 'embedded_metadata', 'shape_inference', 'catalog_observation']
confidence: t.Literal['high', 'medium', 'low']
attribute
attribute
confidence: t.Literal['high', 'medium', 'low']
evidence: str
attribute
attribute
evidence: str
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.SearchRequestModel
class
class
class agentgrep.mcp.SearchRequestModel

Bases: AgentGrepModel

Validated search request payload.

terms: list[str]
attribute
attribute
terms: list[str]
agent: AgentSelector
attribute
attribute
agent: AgentSelector
scope: SearchScopeName
attribute
attribute
scope: SearchScopeName
case_sensitive: bool
attribute
attribute
case_sensitive: bool
limit: int | None
attribute
attribute
limit: int | None
cursor: str | None
attribute
attribute
cursor: str | None
cwd: str | None
attribute
attribute
cwd: str | None
repo: str | None
attribute
attribute
repo: str | None
branch: str | None
attribute
attribute
branch: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.SearchToolResponse
class
class
class agentgrep.mcp.SearchToolResponse

Bases: AgentGrepModel

Structured response for the MCP search tool.

schema_version: str
attribute
attribute
schema_version: str
request: SearchRequestModel
attribute
attribute
request: SearchRequestModel
stats: ResultStatsModel
attribute
attribute
stats: ResultStatsModel
page: PageInfoModel
attribute
attribute
page: PageInfoModel
status: RunStatusModel
attribute
attribute
status: RunStatusModel
diagnostics: list[DiagnosticModel]
attribute
attribute
diagnostics: list[DiagnosticModel]
results: list[SearchRecordModel]
attribute
attribute
results: list[SearchRecordModel]
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.FindRequestModel
class
class
class agentgrep.mcp.FindRequestModel

Bases: AgentGrepModel

Validated find request payload.

pattern: str | None
attribute
attribute
pattern: str | None
agent: AgentSelector
attribute
attribute
agent: AgentSelector
limit: int | None
attribute
attribute
limit: int | None
cursor: str | None
attribute
attribute
cursor: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.FindToolResponse
class
class
class agentgrep.mcp.FindToolResponse

Bases: AgentGrepModel

Structured response for the MCP find tool.

schema_version: str
attribute
attribute
schema_version: str
request: FindRequestModel
attribute
attribute
request: FindRequestModel
stats: ResultStatsModel
attribute
attribute
stats: ResultStatsModel
page: PageInfoModel
attribute
attribute
page: PageInfoModel
status: RunStatusModel
attribute
attribute
status: RunStatusModel
diagnostics: list[DiagnosticModel]
attribute
attribute
diagnostics: list[DiagnosticModel]
results: list[FindRecordModel]
attribute
attribute
results: list[FindRecordModel]
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ResultStatsModel
class
class
class agentgrep.mcp.ResultStatsModel

Bases: AgentGrepModel

Counters collected while building one MCP result page.

searched is tool-relative: search reports records examined, while find reports sources examined.

sources: int
attribute
attribute
sources: int
searched: int
attribute
attribute
searched: int
matched: int
attribute
attribute
matched: int
emitted: int
attribute
attribute
emitted: int
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.PageInfoModel
class
class
class agentgrep.mcp.PageInfoModel

Bases: AgentGrepModel

Pagination metadata for a result page.

limit: int | None
attribute
attribute
limit: int | None
count: int
attribute
attribute
count: int
next_cursor: str | None
attribute
attribute
next_cursor: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.RunStatusModel
class
class
class agentgrep.mcp.RunStatusModel

Bases: AgentGrepModel

Search or find completion state.

state: t.Literal['complete', 'bounded', 'truncated', 'cancelled', 'approximate', 'failed']
attribute
attribute
state: t.Literal['complete', 'bounded', 'truncated', 'cancelled', 'approximate', 'failed']
reason: str | None
attribute
attribute
reason: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.DiagnosticModel
class
class
class agentgrep.mcp.DiagnosticModel

Bases: AgentGrepModel

Machine-readable result diagnostic.

code: str
attribute
attribute
code: str
message: str
attribute
attribute
message: str
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.InspectResultRequest
class
class
class agentgrep.mcp.InspectResultRequest

Bases: AgentGrepModel

Validated inspect-result request payload.

ref: str
attribute
attribute
ref: str
sample_size: int
attribute
attribute
sample_size: int
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.InspectResultResponse
class
class
class agentgrep.mcp.InspectResultResponse

Bases: AgentGrepModel

Records read through an opaque result ref.

schema_version: str
attribute
attribute
schema_version: str
ref: str
attribute
attribute
ref: str
sample_count: int
attribute
attribute
sample_count: int
records: list[SearchRecordModel]
attribute
attribute
records: list[SearchRecordModel]
error_message: str | None
attribute
attribute
error_message: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.StoreDescriptorModel
class
class
class agentgrep.mcp.StoreDescriptorModel

Bases: AgentGrepModel

Catalog descriptor for one on-disk agent store.

schema_version: str
attribute
attribute
schema_version: str
kind: t.Literal['store']
attribute
attribute
kind: t.Literal['store']
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store_id: str
attribute
attribute
store_id: str
role: str
attribute
attribute
role: str
format: str
attribute
attribute
format: str
path_pattern: str
attribute
attribute
path_pattern: str
env_overrides: list[str]
attribute
attribute
env_overrides: list[str]
platform_variants: dict[str, str]
attribute
attribute
platform_variants: dict[str, str]
coverage: str
attribute
attribute
coverage: str
version_strategies: list[str]
attribute
attribute
version_strategies: list[str]
observed_version: str | None
attribute
attribute
observed_version: str | None
observed_at: str | None
attribute
attribute
observed_at: str | None
upstream_ref: str | None
attribute
attribute
upstream_ref: str | None
schema_notes: str | None
attribute
attribute
schema_notes: str | None
sample_record: str | None
attribute
attribute
sample_record: str | None
search_by_default: bool | None
attribute
attribute
search_by_default: bool | None
search_notes: str | None
attribute
attribute
search_notes: str | None
distinguishes_from: list[str]
attribute
attribute
distinguishes_from: list[str]
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ListStoresRequest
class
class
class agentgrep.mcp.ListStoresRequest

Bases: AgentGrepModel

Validated list-stores request payload.

agent: AgentSelector
attribute
attribute
agent: AgentSelector
role_filter: str | None
attribute
attribute
role_filter: str | None
search_default_only: bool
attribute
attribute
search_default_only: bool
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ListStoresResponse
class
class
class agentgrep.mcp.ListStoresResponse

Bases: AgentGrepModel

Structured response for the MCP list_stores tool.

schema_version: str
attribute
attribute
schema_version: str
stores: list[StoreDescriptorModel]
attribute
attribute
stores: list[StoreDescriptorModel]
total: int
attribute
attribute
total: int
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.GetStoreDescriptorRequest
class
class
class agentgrep.mcp.GetStoreDescriptorRequest

Bases: AgentGrepModel

Validated get-store-descriptor request payload.

store_id: str
attribute
attribute
store_id: str
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ListSourcesRequest
class
class
class agentgrep.mcp.ListSourcesRequest

Bases: AgentGrepModel

Validated list-sources request payload.

agent: AgentSelector
attribute
attribute
agent: AgentSelector
path_kind_filter: t.Literal['history_file', 'session_file', 'sqlite_db', 'store_file'] | None
attribute
attribute
path_kind_filter: t.Literal['history_file', 'session_file', 'sqlite_db', 'store_file'] | None
source_kind_filter: t.Literal['json', 'jsonl', 'sqlite', 'text', 'opaque'] | None
attribute
attribute
source_kind_filter: t.Literal['json', 'jsonl', 'sqlite', 'text', 'opaque'] | None
coverage_filter: t.Literal['default_search', 'inspectable', 'catalog_only', 'private'] | None
attribute
attribute
coverage_filter: t.Literal['default_search', 'inspectable', 'catalog_only', 'private'] | None
include_non_default: bool
attribute
attribute
include_non_default: bool
limit: int | None
attribute
attribute
limit: int | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ListSourcesResponse
class
class
class agentgrep.mcp.ListSourcesResponse

Bases: AgentGrepModel

Structured response for the MCP list_sources tool.

schema_version: str
attribute
attribute
schema_version: str
sources: list[SourceRecordModel]
attribute
attribute
sources: list[SourceRecordModel]
total: int
attribute
attribute
total: int
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.FilterSourcesRequest
class
class
class agentgrep.mcp.FilterSourcesRequest

Bases: AgentGrepModel

Validated filter-sources request payload.

pattern: str | None
attribute
attribute
pattern: str | None
agent: AgentSelector
attribute
attribute
agent: AgentSelector
limit: int | None
attribute
attribute
limit: int | None
cursor: str | None
attribute
attribute
cursor: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.DiscoverySummaryRequest
class
class
class agentgrep.mcp.DiscoverySummaryRequest

Bases: AgentGrepModel

Validated summarize-discovery request payload.

agent: AgentSelector
attribute
attribute
agent: AgentSelector
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.DiscoverySummaryResponse
class
class
class agentgrep.mcp.DiscoverySummaryResponse

Bases: AgentGrepModel

Aggregate counts of discovered sources.

schema_version: str
attribute
attribute
schema_version: str
total_sources: int
attribute
attribute
total_sources: int
sources_by_agent: dict[str, int]
attribute
attribute
sources_by_agent: dict[str, int]
sources_by_format: dict[str, int]
attribute
attribute
sources_by_format: dict[str, int]
sources_by_kind: dict[str, int]
attribute
attribute
sources_by_kind: dict[str, int]
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ValidateQueryRequest
class
class
class agentgrep.mcp.ValidateQueryRequest

Bases: AgentGrepModel

Validated validate-query request payload.

Supply terms to dry-run literal/regex matching against sample_text, query to validate query-language syntax, or both.

terms: list[str] | None
attribute
attribute
terms: list[str] | None
query: str | None
attribute
attribute
query: str | None
case_sensitive: bool
attribute
attribute
case_sensitive: bool
sample_text: str
attribute
attribute
sample_text: str
_require_terms_or_query()
method
method
_require_terms_or_query()

Require at least one of terms or query.

Return type:

ValidateQueryRequest

_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.ValidateQueryResponse
class
class
class agentgrep.mcp.ValidateQueryResponse

Bases: AgentGrepModel

Result of a dry-run query validation.

matches / regex_valid describe the literal/regex dry-run over terms; query_valid describes query-language parse + compile and is None when no query was supplied.

schema_version: str
attribute
attribute
schema_version: str
matches: bool
attribute
attribute
matches: bool
regex_valid: bool
attribute
attribute
regex_valid: bool
query_valid: bool | None
attribute
attribute
query_valid: bool | None
error_message: str | None
attribute
attribute
error_message: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.RecentSessionsRequest
class
class
class agentgrep.mcp.RecentSessionsRequest

Bases: AgentGrepModel

Validated recent-sessions request payload.

agent: AgentSelector
attribute
attribute
agent: AgentSelector
hours: int
attribute
attribute
hours: int
limit: int | None
attribute
attribute
limit: int | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.RecentSessionsResponse
class
class
class agentgrep.mcp.RecentSessionsResponse

Bases: AgentGrepModel

Recently modified sources.

schema_version: str
attribute
attribute
schema_version: str
cutoff_iso: str
attribute
attribute
cutoff_iso: str
sources: list[SourceRecordModel]
attribute
attribute
sources: list[SourceRecordModel]
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.InspectSampleRequest
class
class
class agentgrep.mcp.InspectSampleRequest

Bases: AgentGrepModel

Validated inspect-record-sample request payload.

adapter_id: str
attribute
attribute
adapter_id: str
source_path: str
attribute
attribute
source_path: str
sample_size: int
attribute
attribute
sample_size: int
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.InspectSampleResponse
class
class
class agentgrep.mcp.InspectSampleResponse

Bases: AgentGrepModel

Sample records read from one source.

schema_version: str
attribute
attribute
schema_version: str
adapter_id: str
attribute
attribute
adapter_id: str
sample_count: int
attribute
attribute
sample_count: int
records: list[SearchRecordModel]
attribute
attribute
records: list[SearchRecordModel]
error_message: str | None
attribute
attribute
error_message: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.BackendAvailabilityModel
class
class
class agentgrep.mcp.BackendAvailabilityModel

Bases: AgentGrepModel

Selected read-only subprocess backends.

find_tool: str | None
attribute
attribute
find_tool: str | None
grep_tool: str | None
attribute
attribute
grep_tool: str | None
json_tool: str | None
attribute
attribute
json_tool: str | None
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentgrep.mcp.CapabilitiesModel
class
class
class agentgrep.mcp.CapabilitiesModel

Bases: AgentGrepModel

Static MCP capability summary.

schema_version: str
attribute
attribute
schema_version: str
name: str
attribute
attribute
name: str
version: str
attribute
attribute
version: str
read_only: bool
attribute
attribute
read_only: bool
agents: list[t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']]
attribute
attribute
agents: list[t.Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']]
search_scopes: list[SearchScopeName]
attribute
attribute
search_scopes: list[SearchScopeName]
adapters: list[str]
attribute
attribute
adapters: list[str]
tools: list[str]
attribute
attribute
tools: list[str]
resources: list[str]
attribute
attribute
resources: list[str]
prompts: list[str]
attribute
attribute
prompts: list[str]
backends: BackendAvailabilityModel
attribute
attribute
backends: BackendAvailabilityModel
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}
attribute
attribute
model_config: t.ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Server helpers

agentgrep.mcp.normalize_agent_selection(agent)
function
function
agentgrep.mcp.normalize_agent_selection(agent)

Convert a single MCP agent selector into agentgrep agents.

Parameters:

agent (AgentSelector)

Return type:

tuple[str, ...]

agentgrep.mcp.list_source_models(agent='all')
function
function
agentgrep.mcp.list_source_models(agent='all')

Return discovered sources as typed MCP payloads.

Parameters:

agent (AgentSelector)

Return type:

list[SourceRecordModel]

agentgrep.mcp.build_capabilities()
function
function
agentgrep.mcp.build_capabilities()

Build a typed capability summary.

Return type:

CapabilitiesModel

agentgrep.mcp.build_mcp_server()
function
function
agentgrep.mcp.build_mcp_server()

Build and return the FastMCP server instance.

Return type:

FastMCP

agentgrep.mcp.main()
function
function
agentgrep.mcp.main()

Run the MCP server over stdio.

Return type:

int