MCQuest MCP
MCQuest MCP is a read-only MCP server that gives AI agents structured, evidence-based access to a project's source code, documentation, and Git state without modifying anything.
Project orientation:
mcquest_project_info,mcquest_project_contextgive high-level overviews of structure, tech stack, directories, and key files.File exploration:
mcquest_list_files,mcquest_find_fileslocate files by directory or filename.Source reading and searching:
mcquest_read_filereads line-numbered code;mcquest_searchruns regex searches;mcquest_find_importsandmcquest_find_usagestrace module dependencies and symbol references.Pattern audits:
mcquest_pattern_auditchecks for predefined responsive/mobile layout risk patterns.Documentation intelligence:
mcquest_list_docs,mcquest_read_doc,mcquest_search_docsprovide read-only access to Markdown docs with line numbers and context.Phase-aware docs:
mcquest_phase_contextfinds phase documentation by query or phase number;mcquest_compare_phasecompares evidence between phases.Cross-evidence search:
mcquest_find_evidencesearches code, docs, and phase evidence together, grouped by evidence type.Read-only Git context:
mcquest_git_contextreports branch, status, recent commits, and changed files without mutating the repository.Safety enforcement: All tools are strictly read-only, confined to the project root, and return raw evidence rather than interpretations or modifications.
Provides read-only Git context, including current branch, repository status, recent commits, and file changes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCQuest MCP Search code and docs for 'responsive overflow' and show recent git changes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
# MCQuest MCP — Read-Only Project Intelligence Server
A reusable, read-only MCP server that gives AI coding agents structured access to a software project's source code and documentation.
Built for and battle-tested on the MCQuest codebase, the server is intentionally maintained as a standalone developer tool outside application repositories so it can be pointed at any repository.
It is an evidence layer, not a decision engine: it reports what is actually in a project, and the AI coding agent performs the reasoning.
Features
Provides 17 read-only tools organized into categories:
Project Structure
Tool | Purpose |
| Compact project overview with structure and key files |
| High-level understanding: tech stack, directories, source areas |
| Recursively list project files with glob pattern filtering |
Source Code Analysis
Tool | Purpose |
| Read bounded file sections with line numbers |
| Regex-based source code search with context |
| Find files by filename (case-insensitive) |
| Find ES module imports referencing a target |
| Find symbol references with word-boundary matching |
| Predefined responsive/layout pattern audit |
| Compact TypeScript/TSX/JS/JSX syntax diagnostics with context |
Documentation Intelligence
Tool | Purpose |
| List Markdown documentation files |
| Read Markdown docs with line numbers |
| Regex/text search across docs |
| Locate phase docs (supports |
| Compare documentation between two phases |
Cross-Evidence & Git
Tool | Purpose |
| Search code + docs in one call, grouped by evidence type |
| Read-only Git: branch, status, recent commits, changes |
The server does not modify the target project.
Related MCP server: reflens
Quick Start
Requires Python 3.10+ and uv.
# 1. Get the code
# (or clone your fork / place it somewhere outside your app repos)
cd mcquest-mcp
# 2. Install dependencies (runtime dep is only the MCP SDK;
# pytest is installed as a dev-only dependency)
uv sync
# 3. Run it, pointing the server at the repository you want to inspect
# Windows (PowerShell):
uv run mcquest-mcp --project "D:\path\to\your\project"
# macOS / Linux:
uv run mcquest-mcp --project /path/to/your/projectImportant: you must tell the server which repository to inspect. Either pass
--project <PATH>(absolute or relative), or set theMCQUEST_PROJECT_ROOTenvironment variable. If neither is supplied, startup fails with a clear error — the server never silently assumes a repository.--projecttakes precedence over the environment variable.
The same installed server is safely reused across repositories by changing the
--project argument, e.g.:
uv run mcquest-mcp --project "D:\DeveloperTools\mcquest-mcp" # this repo
uv run mcquest-mcp --project "D:\Some\Other\Repository" # anything elseConfiguration
Setting | Default | Purpose |
| (none — startup fails if unset) | Absolute or relative path to the project root all tools are confined to |
Path containment. Every tool resolves its inputs against
MCQUEST_PROJECT_ROOTand rejects path traversal (../, absolute escapes) outside that boundary.Default search paths. Several tools default to
frontend/src(source) anddocs(documentation). Passpath=/docs_path=explicitly for other layouts.Phase docs.
mcquest_phase_contextandmcquest_compare_phaseassume docs are named likedocs/phase-<N>...mdunder the documentation path.
Registering with an MCP client
Wire the mcquest-mcp console script into your MCP client's server configuration.
Example (JSON, e.g. Cline/Claude local config):
{
"mcpServers": {
"mcquest-mcp": {
"command": "uv",
"args": ["run", "mcquest-mcp", "--project", "C:/path/to/your/project"]
}
}
}Or run the MCP Inspector during development:
uv run python -m mcp dev dev_server.pyDocumentation Awareness
The documentation tools give the AI agent read-only access to project Markdown
documentation (e.g. docs/, memory-bank/), including previous audit and
implementation phases.
mcquest_list_docs— list Markdown files under a project-relative path.mcquest_read_doc— read a Markdown file with exact line numbers.mcquest_search_docs— regex/text search across Markdown docs, returning file path, line number, matching line, and surrounding context.mcquest_phase_context— Two modes:querymode (free-text) andphasemode (structured lookup, e.g.phase="61"). Phase mode groups results by document type.
These tools preserve the original Markdown evidence and line references. They do not summarize, rewrite, or interpret the documentation; they return the raw evidence so the AI agent can reason about it.
Diagnostics (TypeScript / TSX / JS / JSX)
mcquest_diagnostics gives the AI agent compact syntax diagnostics for a
single source file without reading the whole file. It is the preferred tool when
a compiler/parser error location is already known (e.g. '}' expected,
')' expected, TS1005, or an error reported at a specific line/column),
especially in large .tsx files.
What it does
Runs the selected project's own Node runtime against the project-local TypeScript compiler parser (
node_modules/typescript/lib/typescript.js).Uses
ts.createSourceFile— a pure parser: no module resolution, no type checking, notsconfig, no application code.Returns each diagnostic's code, severity, message, exact 1-based line/column, a small line-numbered source context window, and TypeScript-provided related locations when available (e.g. the opening
{that caused a parser mismatch).Bounds output:
context_lines(default 12, max 25) andmax_diagnostics(default 20, max 50). A 1,400+ line file never causes the whole file to be returned.
Parameters
Param | Default | Notes |
| (required) | Project-relative |
| 12 | Source lines around each diagnostic (0–25) |
| 20 | Diagnostics returned (1–50) |
|
| Only diagnostics at this 1-based line |
|
| Only diagnostics at this 1-based column (usually with |
|
| Only |
When to use it
TypeScript syntax errors, TSX parser errors,
'}'/')'/']'expected, unexpected tokens, unterminated strings/templates, JSX closing-tag problems.A compiler/parser error with a known line/column in a large file — use this instead of reading the entire source file.
When NOT to use it
Do not use it for semantic/type errors (e.g.
tsc --noEmitstyle type mismatches) — this version reports syntax diagnostics only.Do not use it to read a file's content; use
mcquest_read_file.
TypeScript availability
The tool requires a Node.js runtime on PATH and a project-local TypeScript installation in the selected project. It never downloads or installs anything. If TypeScript is unavailable it returns:
TypeScript compiler unavailable in selected project.Read-only guarantee
The tool is strictly read-only: it reads the file, parses it, and returns a
report. It never modifies source files, tsconfig, package.json, lockfiles,
node_modules, or generated files, and it never executes application code.
Safety
This MCP is intentionally read-only.
It does not provide:
file editing
file creation
file deletion
shell execution
arbitrary code execution
package installation
Git mutation
commits
pushes
deployment
The server provides evidence; the AI coding agent performs the reasoning. It never
claims runtime verification — static/documentation evidence is always labeled as such
(e.g. RUNTIME VERIFICATION: NOT PERFORMED where applicable).
Narrow subprocess exception. Two tools invoke a fixed, read-only executable — the
same trust posture as running git directly:
mcquest_git_contextrunsgit --no-pagerwith read-only arguments.mcquest_diagnosticsruns the project's own Node runtime against the project-local TypeScript compiler parser (node_modules/typescript/lib/typescript.js) usingts.createSourceFile— a pure parser. It never runsnpx,npm,tsc,tsconfig,createProgram, a LanguageService, or application code, and never writes files.
This is not arbitrary project process execution: the executable name is fixed, no shell is used, all paths are validated inside the project root, source is passed via stdin, and a timeout is enforced.
Recommended Cline Usage Flow
mcquest_project_context— First call for project orientationmcquest_phase_context(phase="N")— Understand a specific phasemcquest_find_evidence(query="...")— Cross-search code + docsmcquest_read_file/mcquest_read_doc— Read specific filesmcquest_diagnostics— Investigate a TypeScript/TSX/JS/JSX parser or compiler error instead of reading a large filemcquest_git_context— Check recent changes before investigationmcquest_compare_phase(from_phase="61", to_phase="62")— Compare phase docs
Development & Testing
uv syncinstalls runtime + dev dependencies.Run the regression suite with:
uv run pytest -qThe suite guards: the exact 17-tool registration, path-security/traversal, the read-only guarantee, output bounds, evidence-neutral
compare_phaseoutput, thefind_evidence(scope="phase")behavior, and themcquest_diagnosticssyntax-diagnostic tool (registration, schema, context/max limits, large files, missing TypeScript, security containment, read-only behavior).Runtime dependency is only
mcp[cli]>=2,<3;pytestis a dev-only dependency.Live
mcquest_diagnosticstests are skipped unlessMCQUEST_TEST_TYPESCRIPT_LIBpoints at a realtypescript.js; nothing is downloaded to make tests pass.
Known Legacy Defaults
The tool names retain the mcquest_ prefix and several defaults assume an
MCQuest-style layout (e.g. frontend/src, docs, specific config filenames in
mcquest_project_info / mcquest_project_context, responsive-pattern categories in
mcquest_pattern_audit). These are intentionally retained for backward
compatibility while the server is progressively generalized. The project root is no
longer hard-coded: it comes from --project or MCQUEST_PROJECT_ROOT, and startup
fails if neither is supplied. Git tools are limited to read-only inspection
commands.
Version History
v0.4.0 — Added
mcquest_diagnostics: read-only, project-local TypeScript/TSX/JS/JSX syntax diagnostics via the project's ownnode_modules/typescriptparser (ts.createSourceFile), with compact line-numbered context, related locations, and strict output bounds.v0.3.0 — Evidence-neutral
compare_phasevocabulary (ADDED/REMOVED/COMMON,RUNTIME VERIFICATION: NOT PERFORMED), fixedfind_evidence(scope="phase"), added a dev-only pytest regression suite.v0.2.0 — Added
project_context,find_evidence,git_context,compare_phase. Improved all tool descriptions. Addedphaseparameter tophase_contextwith structured lookup grouped by document type.v0.1.0 — Initial release with 12 read-only tools.
Requirements
Windows, macOS, or Linux
Python 3.10+
uvMCP Python SDK
Node.js only if using MCP Inspector, or when using
mcquest_diagnosticsagainst a project that has TypeScript installed locally (node_modules/typescript)
Install
Clone or place the server somewhere outside your application repositories, then see Quick Start.
Available Tools
16 toolsmcquest_compare_phaseA
READ ONLY. Compare documentation evidence between two phases. Returns differences in document sets using terminology: EXISTING, RESOLVED, NEW, POTENTIAL REGRESSION, UNKNOWN. Use to understand what changed between phases.
Inputs: to_phase (required), from_phase (required), path, max_results. Returns: result
mcquest_find_evidenceA
READ ONLY. Search across code, documentation, and phase evidence in a single call. Returns results grouped by CODE EVIDENCE and DOCUMENTATION EVIDENCE. Scope can be 'code', 'docs', 'phase', or 'all'. Optionally filter by phase. Use this instead of separately searching code and docs.
Inputs: query (required), path, phase, scope, +3 more. Returns: result
mcquest_find_filesA
READ ONLY. Find project files by filename using case-insensitive substring matching. Returns relative file paths. Use when you know a filename but not its location.
Inputs: query (required), path, max_results. Returns: result
mcquest_find_importsA
READ ONLY. Find ES module imports that reference a target component/module. Searches .ts, .tsx, .js, .jsx files. Returns file:line:import-statement. Useful for discovering which files depend on a module.
Inputs: target (required), path, max_results. Returns: result
mcquest_find_usagesA
READ ONLY. Find references to a symbol across MCQuest source files using word-boundary matching. Returns file:line:line-content. Use for discovering where a component, function, or variable is used.
Inputs: symbol (required), path, max_results, file_pattern. Returns: result
mcquest_git_contextA
READ ONLY. Provide read-only Git investigation information. Returns current branch, working-tree status, recent commits, and recently changed files. Does NOT perform commits, adds, resets, checkouts, merges, rebases, pushes, or pulls. Use to understand recent changes and current branch state.
Inputs: max_changes, max_commits. Returns: result
mcquest_list_docsA
READ ONLY. List Markdown documentation files under a project directory. Excludes dependency/generated directories and non-Markdown files. Returns relative file paths. Use to discover available documentation before reading specific files.
Inputs: path, pattern, max_results. Returns: result
mcquest_list_filesA
READ ONLY. List source files under a project directory. Excludes node_modules, .git, build output, virtual environments, and other generated/dependency directories. Returns relative file paths. Prefer this over searching when you know which directory to inspect.
Inputs: path, pattern, max_results. Returns: result
mcquest_pattern_auditA
READ ONLY. Run predefined MCQuest responsive/layout pattern searches. Categories include: viewport-width, large-min-width, large-fixed-width, nowrap, negative-horizontal-margin, horizontal-transform, negative-position, overflow-x, min-width, fixed-position, sticky-position, or 'all'. Returns evidence only — no modifications. Use for auditing potential mobile/responsive issues.
Inputs: path, categories, max_results_per_category. Returns: result
mcquest_phase_contextA
READ ONLY. Locate relevant phase/stage documentation. Use EITHER 'query' (free-text search, e.g. 'responsive overflow', 'Android') OR 'phase' (phase number, e.g. '61', '61-Part-II-A'). When 'phase' is provided, results are grouped by document type (implementation reports, audits, completions). Returns each match with its nearest heading, line numbers, and surrounding context. Preserves original evidence. Works for past and future phases.
Inputs: path, phase, query, max_results, +3 more. Returns: result
mcquest_project_contextA
READ ONLY. Provide a compact high-level understanding of the MCQuest project. Returns technology stack, major directories, important source areas, documentation paths, and key configuration files. Use this as the first context call before a large investigation.
Inputs: no named parameters. Returns: result
mcquest_project_infoA
READ ONLY. Get a compact overview of the MCQuest project structure and important files. Returns project root, top-level directories, and key configuration files. Use this as the first context call before a large investigation.
Inputs: no named parameters. Returns: result
mcquest_read_docA
READ ONLY. Read a Markdown documentation file with exact line numbers. Use line ranges whenever possible instead of requesting huge files. Returns line-numbered Markdown content.
Inputs: path (required), end_line, start_line. Returns: result
mcquest_read_fileA
READ ONLY. Read a source file with exact line numbers. Use line ranges whenever possible instead of requesting entire files to reduce token consumption. Returns line-numbered content.
Inputs: path (required), end_line, start_line. Returns: result
mcquest_searchA
READ ONLY. Search MCQuest source files using a regular expression. Returns exact relative file paths, line numbers, matching lines, and limited surrounding context. Prefer this for locating code patterns.
Inputs: pattern (required), path, max_results, file_pattern, +2 more. Returns: result
mcquest_search_docsA
READ ONLY. Search Markdown documentation using a regex or text pattern. Returns exact file paths, line numbers, matching lines, and limited surrounding context. Prefer this for finding specific topics across all documentation.
Inputs: pattern (required), path, max_results, file_pattern, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have clearly distinct purposes: listing files, reading files, searching code, finding imports, auditing patterns, and git status are all unambiguous. However, mcquest_project_context and mcquest_project_info significantly overlap — both serve as the first high-level project overview call — which introduces one notable source of confusion.
All tools share the consistent mcquest_ prefix and use clean snake_case, making the set feel cohesive. Naming is not perfectly uniform because some tools follow action-based patterns like list_files or read_file, while others use noun-oriented names like project_context, phase_context, or find_evidence, but the overall pattern remains predictable.
16 tools is slightly above the ideal 3–15 range, but the count is justified by a broad read-only investigative scope covering code, documentation, git state, phase evidence, and responsive-pattern auditing. The set feels reasonably sized rather than bloated, though a couple of closely related tools contribute to mild redundancy.
The tool surface thoroughly covers the domain of read-only project investigation: project orientation, file navigation, code search, dependency analysis, symbol usage, responsive audits, documentation exploration, phase comparisons, git context, and combined evidence lookup. There are no obvious dead ends or missing core operations within its stated read-only scope.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for AI coding agents to inspect repositories, audit code quality, route engineering skills, and plan safe issue/PR workflows.1MIT
- AlicenseAqualityDmaintenanceAn MCP server that indexes reference repositories and provides tools for AI coding agents to retrieve lossless code context, enabling reasoning over codebases larger than the agent's context window.82Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that gives coding agents structured, read-only access to sibling repositories, ensuring security by design with zero write tools.MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for code reading with intelligent caching, line-range selection, and language detection, enabling AI assistants to efficiently and safely explore file systems.MIT