# project-notes MCP Server

A custom [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server written in TypeScript. It lets AI clients store, search, and summarize short notes about a codebase during a coding session.

## Overview

This server exposes project notes through MCP **tools** (for actions) and a **resource** (for read-only context). It uses stdio transport, which makes it compatible with local AI clients like Cursor and Claude Desktop.

Notes are kept in memory for the lifetime of the server process. They are useful as a session scratchpad, not as permanent project documentation.

## Features

| Capability | Type | Description |
|------------|------|-------------|
| `add_note` | Tool | Add a note with a title and content |
| `search_notes` | Tool | Search notes by keyword in title or content |
| `notes://summary` | Resource | Return note count and a list of all note titles |

## Tech Stack

- **Runtime:** Node.js (ESM)
- **Language:** TypeScript
- **MCP SDK:** `@modelcontextprotocol/sdk`
- **Validation:** Zod (auto-generates JSON Schema for tool inputs)
- **Transport:** stdio

## Project Structure

```
mcp1/
├── src/
│   └── index.ts       # Server entry point
├── dist/
│   └── index.js       # Compiled output
├── .cursor/
│   └── mcp.json       # Cursor MCP configuration
├── package.json
├── tsconfig.json
└── README.md
```

## Requirements

- Node.js 18+
- npm

## Installation

```bash
npm install
```

## Build

```bash
npm run build
```

This compiles TypeScript from `src/` into `dist/`.

## Run

```bash
npm start
```

The server communicates over stdio and waits for MCP client messages. Debug output is written to **stderr** only — never use `console.log`, as stdout must remain reserved for JSON-RPC.

On startup you should see:

```
[project-notes] Server started
```

## Client Configuration

### Cursor

Add or update `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "project-notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp1/dist/index.js"]
    }
  }
}
```

Replace the path with the absolute path to your built `dist/index.js`. Reload MCP servers in Cursor settings after building.

### Claude Desktop

Add to your Claude Desktop config:

| Platform | Config path |
|----------|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "project-notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp1/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop after saving.

## Testing

Use the official MCP Inspector for interactive testing:

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```

From the inspector UI you can:

1. Call `add_note` with `title` and `content`
2. Call `search_notes` with a `query`
3. Read the `notes://summary` resource

## Usage Examples

Once connected to a client, you can ask the AI to:

- **Add a note:** “Add a note: auth module was refactored to use JWT”
- **Search notes:** “Search notes for auth”
- **List notes:** “What project notes do we have?”

Example tool inputs:

```json
{
  "title": "Auth refactor",
  "content": "JWT tokens now replace session cookies in src/auth/"
}
```

```json
{
  "query": "auth"
}
```

## Implementation Details

### Tools vs Resources

- **Tools** are for actions the model can invoke (`add_note`, `search_notes`).
- **Resources** provide context the host can read without a tool call (`notes://summary`).

Using a resource for summaries avoids adding extra tools and helps keep the tool list small.

### Input Validation

Tool parameters are defined with Zod schemas. The MCP SDK converts these into JSON Schema so clients know what inputs each tool accepts.

### Error Handling

The `add_note` tool wraps logic in a try/catch and returns `isError: true` on failure. This tells the model the call failed instead of treating the response as a successful result.

### Response Format

All tool handlers return MCP content blocks:

```typescript
{
  content: [{ type: "text", text: "..." }]
}
```

### In-Memory Storage

Notes are stored in a simple array inside the running process:

```typescript
const notes: { title: string; content: string; ts: string }[] = [];
```

Notes are cleared when the server process restarts or the MCP client reloads the server.

## Scripts

| Command | Description |
|---------|-------------|
| `npm run build` | Compile TypeScript to `dist/` |
| `npm start` | Run the compiled server |
| `npm run dev` | Build and run in one step |

## License

MIT