The fastest way to understand a new codebase is to ask it questions. Codewalk makes that possible through an MCP server and a REST API. This post is a hands-on demo: we index FastAPI and explore it with both interfaces.

You can follow along with any public repo. FastAPI is a good choice because it is popular, well-structured, and small enough to index locally.

Prefer a visual walkthrough? See all demos →

What you need

Codewalk running locally.
A clone of fastapi/fastapi.
A codewalk.yaml in the FastAPI root. Ours looks like this:

code_guidelines: ""
docs_path: "docs"

indexing:
  branches:
    - master
  exclude:
    - .codewalk/**
    - .git/**
    - .github/**
    - .vscode/**
    - .venv/**
    - venv/**
    - __pycache__/**
    - .pytest_cache/**
    - .mypy_cache/**
    - .ruff_cache/**
    - .tox/**
    - .eggs/**
    - build/**
    - dist/**
    - "*.egg-info/**
    - node_modules/**
    - .next/**
    - .DS_Store
    - "*.pyc"
    - "*.pyo"
    - uv.lock

MCP flow: ask Copilot to explore the code

The MCP server exposes Codewalk as tools inside VS Code Copilot, Cursor, Claude Code, or any MCP-compatible host. After indexing, you can ask natural-language questions.

Step 1 — Index the repo

This is the only setup step. It scans files, chunks and embeds the code, builds the dependency graph, and indexes the docs/ folder.

@codewalk_analyze_codebase

Step 2 — Get oriented

Ask for a high-level overview before diving in.

@codewalk_get_overview

Expected output: tech stack, module list, dependency diagram, and the riskiest files.

Step 3 — Search for a concept

For conceptual questions, run 1-3 parallel searches with different phrasings and synthesize the results.

@codewalk_search_codebase how does dependency injection work in FastAPI
@codewalk_search_codebase FastAPI Depends class implementation
@codewalk_search_codebase dependency overrides testing

This gives you chunked code with file paths and line numbers. Read the chunks, then answer the user or ask a follow-up.

Step 4 — Drill into a specific symbol

Once you know the symbol name, use the dedicated tool instead of search.

@codewalk_explain_function Depends

Step 5 — Check change impact

Before touching a file, ask what breaks.

@codewalk_get_blast_radius_map fastapi/dependencies

Step 6 — Review a diff

Run a review on your working-tree changes. Codewalk uses the git diff, changed files, static analysis, and any indexed graph context.

@codewalk_run_review

Pass target_branch="main" (or any branch) only when you want to diff against that branch. Expected output: a batch of findings with severity, file paths, line numbers, and a short description.

Step 7 — Re-review after fixes

After you accept or reject findings, run a re-review. It starts a fresh review pass and hides any finding you rejected in the previous session.

@codewalk_re_review

Other useful MCP tools in this demo

@codewalk_get_module_info fastapi — files, symbols, and dependencies for the module.
@codewalk_get_reading_order — optimal file reading sequence.
@codewalk_get_execution_flow — module-to-module dependency chains.
@codewalk_find_circular_dependencies — import cycles.
@codewalk_ask_docs how do I mount a sub-application — grounded answers from the indexed docs.

API flow: same intelligence over HTTP

The REST API is useful for scripts, custom frontends, or anywhere you do not want an IDE agent in the loop.

Step 1 — Index the repo

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_path": "/Users/amadhavl/Development/fastapi", "index_mode": "auto"}'

For streaming progress:

curl -X POST http://localhost:8000/analyze/stream \
  -H "Content-Type: application/json" \
  -d '{"repo_path": "/Users/amadhavl/Development/fastapi", "index_mode": "auto"}'

Step 2 — Get the overview

curl "http://localhost:8000/overview?repo_path=/Users/amadhavl/Development/fastapi"

Step 3 — Semantic search

curl -X POST http://localhost:8000/semantic-search \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/Users/amadhavl/Development/fastapi",
    "query": "how does dependency injection work",
    "n_results": 5
  }'

Step 4 — Chat with the agent

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/Users/amadhavl/Development/fastapi",
    "message": "how does dependency injection work in FastAPI?",
    "thread_id": "demo-thread-1"
  }'

The agent calls search_codebase, explain_function, and other tools internally. It expands your question into 1-3 search angles automatically.

Step 5 — Ask the docs

Because we set docs_path: "docs", the API can also answer questions from the FastAPI documentation.

curl -X POST http://localhost:8000/docs/ask \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/Users/amadhavl/Development/fastapi",
    "question": "how do I mount a sub-application",
    "n_results": 5
  }'

Step 6 — Review a diff

By default, POST /review reviews working-tree changes. Pass target_branch only when you want to diff against a branch.

curl -X POST http://localhost:8000/review \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/Users/amadhavl/Development/fastapi"
  }'

For streaming progress:

curl -X POST http://localhost:8000/review/stream \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/Users/amadhavl/Development/fastapi"
  }'

MCP vs API: when to use which

| Use case | Best interface | |---|---| | Exploring code inside an IDE | MCP | | Building a custom UI or automation | REST API | | Reviewing a PR with Copilot | MCP | | Batch scripts or CI integration | REST API | | Natural-language chat with memory | Both (/chat or agent tools) |

Both interfaces share the same index, graph, and embeddings. The difference is who orchestrates the tool calls: the host LLM in MCP, or your code in the API.

Try it on TypeORM too

If you want a TypeScript demo, repeat the same steps with TypeORM. The MCP tool names and API endpoints are identical. Good starter questions:

"How does TypeORM map entities to database tables?"
"Where is the query builder implemented?"
"What breaks if I change the connection logic?"

Summary

Codewalk turns a repo into something you can query. The MCP flow feels like talking to a senior engineer inside your IDE. The API flow gives you the same data as HTTP endpoints. Both start with one indexing call and end with answers that cite real file paths and line numbers.

See all demos →

Index once. Ask anything.