Skip to main content
Glama
negativexq

Repo Context Forge

by negativexq
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Repo Context Forge

repo-context-forge MCP server

Glama MCP server score

Repo Context Forge is a local-first MCP-based repository intelligence platform. It inspects local codebases through deterministic and security-restricted analyzers, then produces compact, source-grounded context packs for coding agents such as Codex, Claude Code, and Cursor.

Current prerelease: v0.2.0-alpha.1 - Local Source-Grounded Repository Agent

Why This Exists

Coding agents often spend substantial time rebuilding the same repository map, symbol index, dependency context, and current-state understanding. Repo Context Forge makes that evidence reusable while preserving repository-relative file and line references.

The platform operates locally. It does not send repository content to a hosted model, execute analyzed code, or install dependencies from analyzed projects.

Related MCP server: ProjectBrain

What It Generates

.context-output/<workspace>/
├── manifest.json
├── project-overview.md
├── repository-map.md
├── architecture.md
├── development-guide.md
├── current-state.md
├── risks-and-debt.md
├── agent-handoff.md
├── symbols.json
├── dependencies.json
├── integrations.json
├── git-state.json
└── bundles/

agent-handoff.md is the primary compact repository index. Bundles under bundles/ gather bounded evidence for a specific objective. Generated context is an index, not a substitute for inspecting source files before editing them.

Key Capabilities

  • Secure named workspaces with path containment, denied-pattern, symlink, binary, and file-size controls.

  • Deterministic repository trees, metadata, and bounded UTF-8 file reads.

  • Lexical text, regex, definition, reference, environment-name, and config-file search without shell commands.

  • Static Python AST symbols, imports, references, callers, callees, and bounded symbol source ranges without importing analyzed modules.

  • Direct dependency declarations, Python internal import graphs, cycle detection, and rule-based integration evidence.

  • Allowlisted read-only local Git status, history, revision comparison, file history, and changed-symbol analysis.

  • Atomic, hash-validated context packs, freshness checks, and deterministic task bundles.

Architecture

flowchart TD
    A[CLI / MCP Clients] --> B[Application Factories]
    B --> C[Repository Intelligence Services]
    C --> C1[Repository Access]
    C --> C2[Code Search]
    C --> C3[Python Symbols]
    C --> C4[Dependency Analysis]
    C --> C5[Read-Only Git Analysis]
    C --> C6[Context Pack Generation]
    C1 --> R[Read-Only Mounted Repositories]
    C2 --> R
    C3 --> R
    C4 --> R
    C5 --> R
    C6 --> O[Writable Context Output]

Typer and FastMCP are adapters. Domain services remain independent of both, and application factories construct explicit dependencies without scanning a repository during import.

Quick Start

Prerequisites are Docker Desktop or a compatible Docker Engine with Docker Compose. Host Python, uv, Ruff, mypy, and pytest are not required.

git clone https://github.com/negativexq/repo-context-forge.git
cd repo-context-forge

docker compose build repo-context-forge
docker compose run --rm repo-context-forge uv run rcf doctor
docker compose run --rm repo-context-forge uv run pytest

The development image uses Python 3.12, pinned uv, the committed uv.lock, a non-root user, and the project installed in editable mode.

Mounting Local Repositories

Copy the public examples and replace only the individual host repository paths:

cp docker-compose.local.example.yml docker-compose.local.yml
cp config.docker.example.yaml config.docker.yaml

Example mapping:

Host:      /Users/example/projects/service-a
Container: /workspaces/service-a

Compose mounts each analyzed repository with :ro; configuration always uses the container path. Never mount an entire home directory, SSH keys, cloud credentials, Docker credentials, or global Git configuration.

docker compose \
  -f docker-compose.yml \
  -f docker-compose.local.yml \
  run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml workspace list

Missing configured mounts fail with a safe invalid-workspace-root error.

Generating a Context Pack

docker compose \
  -f docker-compose.yml \
  -f docker-compose.local.yml \
  run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  context generate service-a

Validate integrity and inspect freshness without regenerating:

docker compose -f docker-compose.yml -f docker-compose.local.yml run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml context validate service-a

docker compose -f docker-compose.yml -f docker-compose.local.yml run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml context freshness service-a

Generated output persists through the writable ./.context-output:/app/.context-output mount. Analyzed repository mounts remain read-only. On macOS Docker Desktop, generated files are visible through the normal bind-mounted project directory and retain Docker Desktop's mapped host ownership behavior.

Creating a Task Bundle

docker compose -f docker-compose.yml -f docker-compose.local.yml run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  context bundle service-a inspect-service \
  --objective "Understand the service and repository interaction" \
  --term service \
  --term repository

Task bundles rank validated seed files, lexical matches, Python symbols, static calls and imports, module dependencies, relevant tests, and available local Git evidence. They do not copy the complete repository.

For a self-contained public demonstration, run:

make docker-demo

This analyzes the synthetic read-only fixture under examples/demo-repository, validates its pack, creates bundles/understand-service.md, and lists generated artifacts.

MCP Servers

Each FastMCP server runs independently over stdio and accepts --config:

Repository MCP tools are read-only, accept repository-relative paths rather than host filesystem paths, and publish model-oriented parameter guidance in their generated schemas. Glama server metadata is provided in glama.json.

Entry point

Purpose

Tools

rcf-mcp-repository

Secure repository files and trees

6

rcf-mcp-code-search

Deterministic lexical search

6

rcf-mcp-symbols

Static Python AST intelligence

8

rcf-mcp-dependencies

Dependency and integration intelligence

6

rcf-mcp-git

Read-only local Git intelligence

7

rcf-mcp-context

Context packs and task bundles

7

Example startup:

docker compose run --rm -i repo-context-forge \
  uv run rcf-mcp-context --config config.docker.yaml

Repository tools: list_workspaces, get_repository_tree, find_files, read_file, read_file_range, get_file_metadata.

Code-search tools: search_text, search_regex, find_definitions, find_references, find_environment_variables, find_config_files.

Symbol tools: list_symbols, get_symbol, find_symbol_definitions, find_symbol_references, get_module_imports, get_symbol_source, get_callers, get_callees.

Dependency tools: get_external_dependencies, get_internal_dependency_graph, find_dependency_cycles, find_external_integrations, get_module_dependencies, find_dependency_usage.

Git tools: get_repository_state, get_git_status, get_recent_commits, get_changed_files, compare_revisions, get_file_history, get_recently_changed_symbols.

Context tools: generate_context_pack, validate_context_pack, get_context_pack_freshness, inspect_context_manifest, create_task_bundle, list_context_artifacts, read_context_artifact.

CLI Reference

All repository-specific commands use one global option:

rcf --config CONFIG workspace list
rcf --config CONFIG repo tree WORKSPACE
rcf --config CONFIG repo find WORKSPACE PATTERN
rcf --config CONFIG repo read WORKSPACE RELATIVE_PATH
rcf --config CONFIG repo read-range WORKSPACE RELATIVE_PATH START END
rcf --config CONFIG repo metadata WORKSPACE RELATIVE_PATH

rcf --config CONFIG search text WORKSPACE QUERY
rcf --config CONFIG search regex WORKSPACE PATTERN
rcf --config CONFIG search definitions WORKSPACE NAME
rcf --config CONFIG search references WORKSPACE NAME
rcf --config CONFIG search env WORKSPACE
rcf --config CONFIG search config-files WORKSPACE

rcf --config CONFIG symbols list WORKSPACE
rcf --config CONFIG symbols find WORKSPACE NAME
rcf --config CONFIG symbols get WORKSPACE QUALIFIED_NAME
rcf --config CONFIG symbols references WORKSPACE NAME
rcf --config CONFIG symbols imports WORKSPACE RELATIVE_PATH
rcf --config CONFIG symbols source WORKSPACE QUALIFIED_NAME
rcf --config CONFIG symbols callers WORKSPACE NAME
rcf --config CONFIG symbols callees WORKSPACE QUALIFIED_NAME

rcf --config CONFIG dependencies list WORKSPACE
rcf --config CONFIG dependencies graph WORKSPACE
rcf --config CONFIG dependencies cycles WORKSPACE
rcf --config CONFIG dependencies integrations WORKSPACE
rcf --config CONFIG dependencies module WORKSPACE MODULE_OR_PATH
rcf --config CONFIG dependencies usage WORKSPACE DEPENDENCY

rcf --config CONFIG git state WORKSPACE
rcf --config CONFIG git status WORKSPACE
rcf --config CONFIG git log WORKSPACE
rcf --config CONFIG git changed-files WORKSPACE
rcf --config CONFIG git compare WORKSPACE BASE TARGET
rcf --config CONFIG git file-history WORKSPACE RELATIVE_PATH
rcf --config CONFIG git changed-symbols WORKSPACE

rcf --config CONFIG context generate WORKSPACE
rcf --config CONFIG context validate WORKSPACE
rcf --config CONFIG context freshness WORKSPACE
rcf --config CONFIG context manifest WORKSPACE
rcf --config CONFIG context list WORKSPACE
rcf --config CONFIG context read WORKSPACE ARTIFACT
rcf --config CONFIG context bundle WORKSPACE NAME --objective OBJECTIVE

rcf --version and rcf doctor do not inspect repositories. Workspace registration mutations remain service-level and in-memory; the CLI exposes only workspace list rather than misleading non-persistent add/remove commands.

Security Model

  • Every repository path is resolved and checked for containment after symlink resolution.

  • POSIX and Windows absolute paths, traversal, external symlinks, denied files, directories-as-files, oversized files, binary data, and invalid UTF-8 are rejected.

  • Denied patterns such as .env, *.pem, *.key, .git, node_modules, and virtual environments take precedence over analysis patterns.

  • Repository-wide scans are deterministic and bounded. Explicit denied reads fail rather than returning misleading empty results.

  • Analyzed modules and dependency manifests are never imported or executed.

  • Git is the only subprocess boundary. It uses argument lists, shell=False, a controlled environment, time/output bounds, and allowlisted read-only commands.

  • Context output has a separate containment policy, fixed artifact names, atomic replacement, and validated SHA-256 manifest hashes.

  • The container has no Docker socket, privileged mode, host networking, SSH forwarding, cloud credentials, or writable analyzed-repository mounts.

See SECURITY.md for vulnerability reporting.

Deterministic Analysis and Limitations

Lexical search may include comments and strings and does not resolve symbol identity. Python AST analysis excludes comments and strings but cannot fully resolve dynamic dispatch, reflection, aliases, or dynamic imports. Only Python has AST symbol support.

Dependency intelligence parses direct declarations from pyproject.toml, requirements files, setup.cfg, static literal setup.py, and package.json. It does not resolve transitive dependencies. Docker and Compose are parsed only as infrastructure evidence. Integration detection is explicit and rule-based.

Git analysis is local and read-only. It returns metadata and changed ranges, not full patches or remote state. Context classifications and architectural interpretations are marked as inferences. Packs can become stale after source, Git, configuration, or generator changes. The alpha local agent remains deterministic at its security boundaries but model behavior is not guaranteed. No embeddings, semantic search, remote API, or web UI are included.

Experimental Local LLM Provider

The v0.2.0-alpha.1 prerelease adds local model connectivity, normal chat, structured tool calls, and a bounded read-only repository agent. It does not enrich context packs or permit repository mutation.

Start Ollama

Ollama is optional and pinned under the Compose llm profile. Its host port is bound only to loopback.

docker compose --profile llm up -d ollama

Pull a Model

Model downloads are always explicit and may require several gigabytes.

docker compose --profile llm exec ollama \
  ollama pull qwen3:4b

The equivalent Make targets are make docker-ollama-up, make docker-model-pull MODEL=qwen3:4b, and make docker-model-list.

Configure the Model

Container commands use the Compose service hostname:

models:
  default: qwen-local
  providers:
    qwen-local:
      provider: ollama
      model: qwen3:4b
      base_url: http://ollama:11434/v1
      api_key: ollama
      enabled: true
      tool_calling: true
      context_window: 32768
      request_timeout_seconds: 120
      temperature: 0
      max_output_tokens: 2048

api_key: ollama is the conventional non-secret placeholder for the local OpenAI-compatible endpoint. Real keys are excluded from public summaries and must never be committed.

Check Model Health

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml models health qwen-local

Run a Chat Test

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  models chat qwen-local "Reply with the word READY."

Run a Tool-Call Test

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml models tool-test qwen-local

The test asks for find_symbol_definitions with synthetic arguments and only prints the validated call. Tool-calling reliability varies by model, especially for smaller models.

Host vs Container URLs

Use http://ollama:11434/v1 from the application container. Use http://127.0.0.1:11434/v1 for a host-side CLI. Container configuration must not use localhost, and Compose does not use host networking.

Current Limitations

  • Model pulling is manual and never occurs during application startup or tests.

  • Only Ollama's OpenAI-compatible local endpoint is supported.

  • Agent execution is stateless, sequential, and read-only; context-pack model enrichment is not implemented.

  • Provider output and tool arguments remain untrusted and strictly validated.

  • Live tests are opt-in: RCF_RUN_OLLAMA_TESTS=1 uv run pytest -m ollama_live.

Experimental MCP Client Runtime

The MCP client runtime starts explicitly configured local servers over stdio, discovers and namespaces their tools, validates call arguments, and normalizes bounded results. MCP commands remain available for manual inspection; the agent uses the same manager and validation boundary for model-requested calls. The six configured servers currently expose 40 tools in total.

Configure MCP Servers

config.docker.example.yaml defines the six existing servers using explicit argument lists. Configuration loading starts no process. Only stdio transport is accepted, namespaces must be unique, and disabled servers are skipped.

mcp:
  default_tool_timeout_seconds: 20
  startup_timeout_seconds: 15
  shutdown_timeout_seconds: 5
  max_tool_result_chars: 30000
  servers:
    symbols:
      transport: stdio
      command: uv
      args: [run, rcf-mcp-symbols, --config, /app/config.docker.yaml]
      enabled: true
      namespace: symbols
      allowed_tools: ["*"]

MCP server stdout is reserved for protocol messages. Diagnostics must use stderr. Child processes receive a conservative runtime environment plus only explicitly configured values.

Inspect Configured Servers

This reads configuration without starting child processes:

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp servers

Check MCP Health

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp health

Health checks eagerly initialize enabled servers, report independent failures, and close every session before returning.

Discover Tools

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp tools

Canonical names use <namespace>.<tool>, such as symbols.find_symbol_definitions. Ordering is deterministic and denied tools are omitted.

Inspect a Tool Schema

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  mcp tool symbols.find_symbol_definitions

Call a Tool Manually

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  mcp call symbols.find_symbol_definitions \
  --arguments '{"workspace":"demo","name":"RepositoryService"}'

Arguments must be a JSON object and are validated against the discovered schema without coercion before one request is sent. MCP error results produce a non-zero status. Resources and URLs in results are never fetched.

Export LLM Tool Definitions

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp llm-tools

OpenAI-compatible function names use reversible namespace__tool encoding, for example symbols__find_symbol_definitions; canonical MCP routing continues to use symbols.find_symbol_definitions. This command does not contact a model.

Current Limitations

Only local stdio child processes are supported. There is no HTTP/SSE transport, automatic retry, remote server discovery, or conversation persistence. Tool configuration is trusted local input, while tool schemas, arguments, and results are untrusted and bounded. Existing repository and read-only Git policies continue to apply.

Experimental Local Repository Agent

The development branch includes a stateless, read-only loop that connects the local model provider to discovered MCP tools. It does not modify repositories, run shell commands, or permit the model to change process configuration. The default policy exposes 38 read-only tools and excludes the two context-output-writing tools.

Start Ollama

docker compose --profile llm up -d ollama
docker compose --profile llm exec ollama ollama list

Model downloads remain an explicit user action; see the local-provider section above.

Configure the Agent

The agent configuration bounds iterations, calls, messages, results, answers, and source references. default_model falls back to models.default when omitted. Parallel calls are disabled. The selected workspace must exist before the provider or MCP processes start.

agent:
  default_model: qwen-local
  max_tool_iterations: 8
  max_tool_calls_per_iteration: 4
  max_total_tool_calls: 20
  max_total_tool_result_chars: 120000
  require_sources_for_repository_claims: true
  allow_parallel_tool_calls: false
  duplicate_tool_call_limit: 2

Ask a Repository Question

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  agent ask demo \
  "Where is WidgetRepository defined?"

Inspect the Tool Trace

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  agent trace demo \
  "Explain how the demo service reaches the repository layer."

The trace contains bounded iteration, tool-name, status, duration, and result size metadata. It omits prompts, complete tool results, API keys, child stderr, and raw provider payloads.

Restrict Servers and Tools

Request filters only reduce locally configured permissions:

uv run rcf --config config.docker.yaml agent ask demo \
  "Where is WidgetRepository defined?" \
  --server symbols \
  --tool symbols.find_symbol_definitions

Use agent tools demo with the same filters to inspect the resulting LLM-facing tool set without calling a model.

Source-Grounding Behavior

Repository citations are checked against source paths and line ranges observed in normalized MCP results. Unsupported citations are reported rather than accepted. If a small model omits citations but valid evidence was collected, the runtime appends a bounded Sources used list deterministically; this list does not claim that every source supports every sentence.

Read-Only Security Model

The workspace is fixed for one run and injected only into tools that declare a workspace parameter. Conflicting workspace arguments are rejected. Calls are schema-validated, sequential, bounded, and routed only through discovered local tools. context.generate_context_pack and context.create_task_bundle are excluded from the default agent policy because they write context output.

Current Limitations

Small-model tool selection and citation quality vary. Analysis remains lexical or static where documented and does not resolve dynamic runtime behavior. There is no conversation persistence, automatic repository editing, cloud provider, semantic retrieval, evaluation framework, or multi-agent orchestration.

The opt-in live test never downloads a model and is skipped by default:

RCF_RUN_OLLAMA_AGENT_TESTS=1 uv run pytest -m ollama_agent_live

Development

make docker-build
make docker-format
make docker-lint
make docker-typecheck
make docker-test
make docker-check
make docker-doctor

Local uv commands remain available, but Docker is the supported validation environment. See CONTRIBUTING.md and AGENTS.md for engineering and source-grounding rules.

Test and Quality Status

The v0.2.0-alpha.1 prerelease was verified in Docker:

Python 3.12
206 tests passed
2 opt-in Ollama tests skipped
87% coverage
Ruff passed
mypy passed

The public CI workflow repeats formatting, linting, strict typing, and tests with coverage on pushes and pull requests.

Roadmap

Future directions are documented in docs/ROADMAP.md. They are plans, not commitments. Evaluation remains the next milestone after this alpha.

License

Repo Context Forge is available under the MIT License.

Available Tools

6 tools
find_filesA

Find repository files by glob pattern. Use this when filenames, extensions or approximate locations are known.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
patternYes
workspaceYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention search recursion, case sensitivity, hidden files, how limit affects results, or whether it respects ignore files. This leaves significant behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two short, front-loaded sentences. The first states the core action, and the second adds a useful use-case hint. There is no waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema covers return values, reducing the burden there. However, the description lacks parameter semantics and behavioral details, leaving gaps for an agent to correctly invoke the tool. It is minimally adequate for a simple tool but incomplete in important areas.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only mentions 'glob pattern' without explaining the expected syntax, the meaning of workspace, or the role of limit. It does not compensate for the missing schema parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's specific action: 'Find repository files by glob pattern.' It distinguishes itself from sibling tools like get_repository_tree or read_file by focusing on pattern-based file discovery rather than tree navigation or content reading.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use the tool: 'Use this when filenames, extensions or approximate locations are known.' This provides clear context, though it does not explicitly name alternatives or define when NOT to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_file_metadataB

Return metadata for one repository file without reading its full contents.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceYes
relative_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
suffixYes
workspaceYes
size_bytesYes
is_directoryYes
relative_pathYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the purpose and hints at performance ('without reading full contents') but does not specify what metadata fields are returned, error handling for missing files, or permission requirements. This is insufficient for a tool with no annotation safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action and scope. It contains no redundant information and is efficiently concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a simple interface and an output schema, which covers return values. However, the description lacks parameter semantics and explicit usage context, and with no annotations, it leaves gaps around error behavior and when to prefer this over get_repository_tree. It is slightly below the minimum viable completeness for a standalone tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate by explaining the parameters. It does not clarify the format of 'relative_path' or what 'workspace' refers to exactly. The parameter names are somewhat self-explanatory but lack necessary detail about path conventions and options.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and clearly identifies the resource ('metadata for one repository file'). It distinguishes itself from sibling tools like read_file and read_file_range by explicitly stating 'without reading its full contents'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without reading its full contents' implies a lightweight metadata use case, but it does not explicitly name alternatives or state when not to use this tool. Sibling tools like read_file are mentioned indirectly but not directly contrasted, making the usage guidance implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_repository_treeA

Return a bounded directory and file map for one repository. Use this to understand repository structure before selecting files. Do not use it to retrieve file contents.

ParametersJSON Schema
NameRequiredDescriptionDefault
max_depthNo
workspaceYes
max_entriesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
entriesYes
truncatedYes
workspaceYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It conveys the output is a bounded directory/file map and clarifies it does not retrieve contents. However, it does not disclose error behavior, whether it follows nested submodules, or any specific limitations beyond 'bounded', leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose in the first and usage guidance in the second. Every word earns its place; no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The purpose and primary usage are clear, and the output schema exists to document return values. However, the lack of parameter explanations and minimal behavioral disclosure make it adequate but incomplete for a tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description does not explain workspace, max_depth, or max_entries. The only hints are 'one repository' and 'bounded', which are indirect and insufficient. The description fails to compensate for the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Describes a specific verb and resource: 'Return a bounded directory and file map for one repository.' It clearly differentiates from siblings by focusing on structure rather than contents, with the explicit exclusion 'Do not use it to retrieve file contents'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: 'Use this to understand repository structure before selecting files.' It also gives an explicit when-not: 'Do not use it to retrieve file contents.' However, it does not name an alternative tool like read_file, so it stops short of a perfect 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_workspacesA

List the local repositories currently available for inspection. Call this before repository-specific tools when the workspace name is unknown.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. The verb 'List' implies a read-only operation, and 'currently available for inspection' adds context about the dynamic nature of available repositories. It could explicitly mention safety, but the read-only nature is clear enough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and resource. Every word earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter listing tool with an output schema (present), the description is complete. It provides the purpose, usage timing, and context, and sibling tools give additional framing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is effectively 100%. The description adds no parameter details, but none are needed. The baseline for zero-parameter tools is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' with a clear resource ('local repositories currently available for inspection'). It distinguishes itself from sibling repository-specific tools by focusing on the workspace enumeration step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: 'Call this before repository-specific tools when the workspace name is unknown.' This provides direct guidance on prerequisites and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileA

Read a bounded amount of one UTF-8 text file. Large, binary, denied or out-of-workspace files are rejected.

ParametersJSON Schema
NameRequiredDescriptionDefault
max_charsNo
workspaceYes
relative_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes
end_lineYes
truncatedYes
workspaceYes
start_lineYes
relative_pathYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses important behavioral traits: the tool only reads UTF-8 text, enforces a size limit, and will reject files that are large, binary, denied, or outside the workspace. This goes beyond the schema and gives agents a clear picture of operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that immediately states the core purpose, then lists rejection conditions. Every word adds value with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers the essential operational envelope: bounded reading, text-only, and rejection conditions. The output schema exists, so return values are documented elsewhere. Minor gaps remain (e.g., what constitutes 'large' or how 'bounded' is determined), but overall it is sufficiently complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explicitly explain any parameter. It vaguely aligns 'bounded amount' with max_chars and mentions workspace/relative path via rejection of out-of-workspace files, but does not clarify required syntax, default behavior, or how max_chars works. The description provides minimal compensation for the missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (read), the resource (one UTF-8 text file), and a key constraint (bounded amount). It also lists rejection criteria (large, binary, denied, out-of-workspace) which further defines the tool's scope and distinguishes it from sibling tools like read_file_range and get_file_metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: read text files up to a bounded size. The rejection of large, binary, denied, and out-of-workspace files gives context about when not to use it. However, it does not explicitly name alternatives or provide when-to-use/when-not-to-use guidance compared to sibling tools like read_file_range or get_file_metadata.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_file_rangeA

Read a specific one-indexed line range from a UTF-8 text file. Prefer this over reading a whole file when the relevant location is already known.

ParametersJSON Schema
NameRequiredDescriptionDefault
end_lineYes
workspaceYes
start_lineYes
relative_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes
end_lineYes
truncatedYes
workspaceYes
start_lineYes
relative_pathYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations available, the description provides some behavioral context (one-indexed, UTF-8) but does not disclose edge-case behavior like invalid line ranges, out-of-bounds, or error handling. For a read operation this is acceptable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no redundant information. The first sentence front-loads the core action and resource, the second adds a usage guideline. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with four self-explanatory parameters and an output schema available. The description covers the essential nuance (one-indexed range, preference over whole-file read), making it sufficiently complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning to start_line and end_line by specifying one-indexed, and to relative_path by specifying UTF-8 text file. However, it does not elaborate on workspace or path resolution beyond what parameter names imply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads a one-indexed line range from a UTF-8 text file, distinguishing it from sibling read_file by focusing on a specific range rather than the whole file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends using this tool over reading a whole file when the relevant location is known, naming the alternative and giving a clear condition for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observedfind_files
    • First observedget_file_metadata
    • First observedget_repository_tree
    • First observedlist_workspaces
    • First observedread_file
    • First observedread_file_range
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool targets a distinct aspect: workspace discovery, structural overview, pattern-based file search, whole-file reading, precise line-range reading, and metadata retrieval. read_file and read_file_range are differentiated by their descriptions, making selection unambiguous.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, using clear verbs (list, get, find, read) and specific nouns. This makes the tool set predictable and easy to navigate.

Tool Count5/5

With six tools, the server is well-scoped for a repository context purpose. Each tool occupies a clear niche with no redundancy, and the count is within the ideal range for a focused utility.

Completeness4/5

The set covers the main workflow: workspace discovery, structure mapping, file search, content reading (whole and partial), and metadata. A content-search (grep-like) tool is a minor gap, but the current surface handles typical repository inspection tasks effectively.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • Repo Interrogator

    taggedzi
    A
    license
    A
    quality
    A
    maintenance
    A local-first MCP server that enables AI tools to safely inspect and search code repositories, providing indexing, deterministic BM25 search, code outlining, and context bundles without code modification.
    9
    1
    MIT

  • ProjectBrain

    yinshaojun001
    A
    license
    B
    quality
    B
    maintenance
    Local MCP server providing project cognition capabilities for AI coding agents, including context packs, impact analysis, and git diff review through stdio communication.
    10
    3
    MIT

  • Sense

    luuuc
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server for codebase context that gives AI coding agents structural understanding through symbol graph, semantic search, blast radius, and convention detection tools.
    35
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/negativexq/repo-context-forge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server