agentgrep.mcp

The MCP module exposes the FastMCP server factory, payload models, prompt helpers, resources, and tool adapters for agentgrep.

Payload models

class agentgrep.mcp.SearchRecordModel
class
class
class agentgrep.mcp.SearchRecordModel

Bases: AgentGrepModel

Normalized search result payload.

schema_version: str
attribute
attribute
schema_version: str
kind: t.Literal['prompt', 'history']
attribute
attribute
kind: t.Literal['prompt', 'history']
agent: t.Literal['codex', 'claude', 'cursor', 'gemini']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor', 'gemini']
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
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.FindRecordModel
class
class
class agentgrep.mcp.FindRecordModel

Bases: AgentGrepModel

Normalized find result payload.

schema_version: str
attribute
attribute
schema_version: str
kind: t.Literal['find']
attribute
attribute
kind: t.Literal['find']
agent: t.Literal['codex', 'claude', 'cursor', 'gemini']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor', 'gemini']
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']
attribute
attribute
path_kind: t.Literal['history_file', 'session_file', 'sqlite_db']
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', 'gemini']
attribute
attribute
agent: t.Literal['codex', 'claude', 'cursor', 'gemini']
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']
attribute
attribute
path_kind: t.Literal['history_file', 'session_file', 'sqlite_db']
source_kind: t.Literal['json', 'jsonl', 'sqlite']
attribute
attribute
source_kind: t.Literal['json', 'jsonl', 'sqlite']
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.SearchToolQuery
class
class
class agentgrep.mcp.SearchToolQuery

Bases: AgentGrepModel

Echo of normalized search tool inputs.

terms: list[str]
attribute
attribute
terms: list[str]
agent: AgentSelector
attribute
attribute
agent: AgentSelector
search_type: SearchTypeName
attribute
attribute
search_type: SearchTypeName
any_term: bool
attribute
attribute
any_term: bool
regex: bool
attribute
attribute
regex: bool
case_sensitive: bool
attribute
attribute
case_sensitive: 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.SearchToolResponse
class
class
class agentgrep.mcp.SearchToolResponse

Bases: AgentGrepModel

Structured response for the MCP search tool.

schema_version: str
attribute
attribute
schema_version: str
query: SearchToolQuery
attribute
attribute
query: SearchToolQuery
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.FindToolQuery
class
class
class agentgrep.mcp.FindToolQuery

Bases: AgentGrepModel

Echo of normalized find tool inputs.

pattern: str | None
attribute
attribute
pattern: str | None
agent: AgentSelector
attribute
attribute
agent: AgentSelector
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.FindToolResponse
class
class
class agentgrep.mcp.FindToolResponse

Bases: AgentGrepModel

Structured response for the MCP find tool.

schema_version: str
attribute
attribute
schema_version: str
query: FindToolQuery
attribute
attribute
query: FindToolQuery
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.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', 'gemini']]
attribute
attribute
agents: list[t.Literal['codex', 'claude', 'cursor', 'gemini']]
search_types: list[SearchTypeName]
attribute
attribute
search_types: list[SearchTypeName]
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