base / base/base-builder-mcp

Bug: Base Builder MCP still fetches documentation from archived base/web path

Open
#16 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
21
Forks
36
PR merge metrics
No merged PRs in 30d

Description

## Summary

`base-builder-mcp` still resolves Base documentation against the old `base/web` repository structure.

The current Base documentation is maintained in `base/docs`.

As a result, valid Base documentation URLs can be converted into obsolete raw GitHub paths and return `404 Not Found`.

## Affected files

- `sidebar.ts`
- `tools.ts`

## Problem

`sidebar.ts` fetches the documentation sidebar from the legacy repository:

```text
https://raw.githubusercontent.com/base/web/refs/heads/master/apps/base-docs/sidebar.ts
```

`tools.ts` also constructs guide URLs using `base/web`:

```ts
const guidePath = guideLink.replace("https://docs.base.org", "");

const githubRawUrl =
`https://raw.githubusercontent.com/base/web/refs/heads/master/apps/base-docs/docs/pages${guidePath}.mdx`;
```

However, `base/web` is archived and the current documentation repository is:

```text
https://github.com/base/docs
```

## Steps to reproduce

Use this current Base documentation URL:

```text
https://docs.base.org/get-started/docs-mcp
```

`getGuide()` converts it into:

```text
https://raw.githubusercontent.com/base/web/refs/heads/master/apps/base-docs/docs/pages/get-started/docs-mcp.mdx
```

That legacy path does not contain the current guide.

The guide currently exists in the active documentation repository at:

```text
base/docs/docs/get-started/docs-mcp.mdx
```

## Expected behavior

A valid page published on `docs.base.org` should be successfully retrieved by the `BuildOnBase` MCP tool.

## Actual behavior

The MCP maps current Base documentation URLs to paths under the archived `base/web` repository.

This can result in `404 Not Found` for valid current documentation.

## Impact

AI agents using Base Builder MCP may:

- fail to retrieve valid Base documentation;
- receive 404 errors for existing guides;
- use stale documentation;
- miss newly added Base features;
- fall back to an outdated embedded sidebar;
- incorrectly conclude that a valid guide does not exist.

This makes the MCP unreliable as an authoritative Base documentation source.

## Suggested fix

Update documentation resolution to use the current Base docs repository:

```text
https://github.com/base/docs
```

The guide resolver should no longer construct URLs under:

```text
base/web/apps/base-docs/docs/pages/
```

The hardcoded fallback sidebar should also be updated or replaced with a source that follows the current documentation structure.

## Suggested tests

Add regression tests for current Base documentation URLs.

For example:

```text
https://docs.base.org/get-started/docs-mcp
```

The test should verify that:

- the resolved source exists;
- the request does not return 404;
- the returned document is not empty;
- current `docs.base.org` routes map to the active documentation repository.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with sidebar.ts and tools.ts, especially getGuide() and the current sidebar and guide URL construction. Trace the https://docs.base.org/get-started/docs-mcp route against the active base/docs repository, then add regression coverage for a successful, non-empty response without a 404. Done means current documentation URLs resolve through the active repository and the fallback sidebar no longer depends on the archived base/web path.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.