Tidewave

0.6.0 verified Mon Apr 27 auth: no javascript

Tidewave is an MCP (Model Context Protocol) server and library for JavaScript/TypeScript frameworks (Next.js, TanStack, Vite). It provides CLI and programmatic interfaces to expose project context to AI agents. Current stable version 0.6.0, released weekly, requires Node >=18 or Bun >=1.0. Ships TypeScript types. Differentiators: deep integration with modern JS frameworks, lightweight, and supports both stdio and HTTP transport.

Common errors

error Cannot find module 'tidewave' or its corresponding type declarations. ↓

cause Missing import or no TypeScript types installed.

fix

Install package: npm install tidewave and ensure TypeScript is present (npm install --save-dev typescript).

error The requested module 'tidewave' does not provide an export named 'startMcpServer' ↓

cause Importing from wrong subpath.

fix

Change import to: import { startMcpServer } from 'tidewave/mcp'

error Error: config is not a valid option. Did you mean projectPath? ↓

cause Using deprecated `config` option.

fix

Use projectPath instead.

Warnings

breaking In v0.2.0, project evaluation scoped tool introduced, changing the tool schema. Older tools may not be compatible. ↓

fix Update to v0.2.3 or later.

deprecated The `config` flag was renamed to `projectPath` in v0.1.0. Old flag no longer works. ↓

fix Use `projectPath` instead of `config`.

gotcha The `prefix` option is only applied at the CLI layer. If using programmatic API, you must handle prefixes manually. ↓

fix Check the CLI documentation for prefix usage; programmatic users ignore prefix.

breaking In v0.2.0, HTTP paths were changed to `/tidewave` prefix. Custom paths may break. ↓

fix Update any custom HTTP handlers to use the `/tidewave` prefix.

gotcha Stdio MCP server (v0.1.0) is experimental and may have issues with large project contexts. ↓

fix Upgrade to v0.2.0+ or use HTTP transport.

Install

npm install tidewave

yarn add tidewave

pnpm add tidewave

Imports

Tidewave
wrong
```
import Tidewave from 'tidewave'
```
correct
```
import { Tidewave } from 'tidewave'
```
Tidewave is a named export, not default. Use named import.
startMcpServer
wrong
```
import { startMcpServer } from 'tidewave'
```
correct
```
import { startMcpServer } from 'tidewave/mcp'
```
The MCP server functions are in a subpath export. Import from 'tidewave/mcp'.
cli
```
import { cli } from 'tidewave/cli'
```
The CLI entry point is exported from 'tidewave/cli'. Not available in the main package.

Quickstart

Initialize Tidewave with project path and optional prefix, then retrieve project context for AI agents.

import { Tidewave } from 'tidewave';

const tw = new Tidewave({
  projectPath: process.cwd(),
  prefix: process.env.TIDEWAVE_PREFIX ?? ''
});

async function main() {
  const context = await tw.getProjectContext();
  console.log('Project context:', context);
}
main();