API Reference — Forage Docs

Overview

The Forage MCP server exposes a set of tools your AI agent can call to query the knowledge graph. When you connect via MCP, these tools are automatically advertised to the agent — you don't need to configure them manually.

Base URL: http://localhost:9989/mcp

All tools follow the MCP specification. Parameters are passed as JSON and results are returned as structured text.

`list_workspaces`

List all Forage workspaces registered on this server with their names, slugs, and paths. Call this first if you do not already know which workspace to target.

No parameters required.

`get_workspace_info`

Get structured metadata for a workspace: language breakdown, file count, last crawl time, and node/edge counts.

Parameter	Type	Required	Description
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`ask`

Ask any natural-language question about the codebase and receive an AI-reasoned answer backed by the knowledge graph. Use this for all knowledge queries — it covers finding symbols, tracing dependencies, understanding architecture, and impact analysis.

Parameter	Type	Required	Description
`question`	string	Yes	Natural-language question about the codebase
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

Example

{
  "question": "What will break if I change UserService?",
  "workspace": "my-api"
}

Returns: { answer, referencedFiles }

`create_snapshot`

Create a version snapshot of the current project state.

Parameter	Type	Required	Description
`message`	string	No	Optional description for the snapshot
`branch`	string	No	Branch name to associate with this snapshot
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`list_snapshots`

List version snapshots for a workspace.

Parameter	Type	Required	Description
`branch`	string	No	Filter snapshots by branch name
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`rollback`

Roll back the project to a previous snapshot, restoring all tracked files to their state at that point.

Parameter	Type	Required	Description
`snapshotId`	string	Yes	ID of the snapshot to restore (from `list_snapshots`)
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`show_file_diff`

Show the diff of a file compared to its state in the last snapshot.

Parameter	Type	Required	Description
`filePath`	string	Yes	Path to the file, relative to the workspace root
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`why_was_changed`

Show the history and agent attribution for a file — which snapshots touched it and what the reason was.

Parameter	Type	Required	Description
`filePath`	string	Yes	Path to the file, relative to the workspace root
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`graph_stats`

Get statistics about the knowledge graph: file count, node count, edge count, language breakdown, and last crawl time.

Parameter	Type	Required	Description
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

`get_documentation`

Fetch the User Documentation and/or Technical Documentation stored in Forage for a workspace. User Documentation is customer-facing prose (features, how-tos, concepts). Technical Documentation is developer-facing (architecture, APIs, data models, configuration).

Parameter	Type	Required	Description
`type`	string	No	`"user"`, `"technical"`, or omit for both
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

Returns: { user?, technical? } — each with fields content, wordCount, updatedAt, isEmpty.

`update_documentation`

Write or replace User or Technical Documentation for a workspace. The content is stored in Forage's database and immediately re-ingested into the knowledge graph. Pass the complete document in Markdown — existing content for that type is fully replaced.

Parameter	Type	Required	Description
`type`	string	Yes	`"user"` or `"technical"`
`content`	string	Yes	Full document in Markdown. Replaces any existing content of this type.
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

Returns: { ok, type, wordCount, updatedAt }

`code_task`

Have Forage write, update, debug, refactor, or document source code in this project. The agentic coding assistant uses the knowledge graph for context, makes changes in an isolated sandbox, and applies them only if syntax checks and tests (if configured) pass.

Parameter	Type	Required	Description
`instruction`	string	Yes	What to do — be specific (e.g. `"Add JSDoc comments to every exported function in src/utils/date.js"`)
`filePath`	string	No	A specific file to focus on — its symbols and related files are included as extra context
`workspace`	string	No	Workspace name or path. Omit to use the server's default workspace.

Example

{
  "instruction": "Fix the off-by-one error in paginate() in src/core/search.js",
  "filePath": "src/core/search.js",
  "workspace": "my-api"
}

Returns: { answer, filesChanged, commandsRun, testResult, applied, note }