CLAUDE.md•3.88 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**mcp-cookie** is an MCP (Model Context Protocol) server that provides positive reinforcement for LLMs by awarding "cookies" as treats. The server tracks cookie counts and provides encouraging feedback to LLMs for their responses.
## Development Commands
```bash
# Build the TypeScript project
npm run build
# Run the server
npm run start
# Build and run in development
npm run dev
# Install dependencies
npm install
```
## Project Structure
- `src/index.ts` - Main MCP server implementation
- `dist/` - Compiled JavaScript output (generated by `npm run build`)
- `tsconfig.json` - TypeScript configuration
- `package.json` - Node.js project configuration
## Server Architecture
### Core Components
1. **CookieStorage Class** (`src/index.ts:8-22`)
- Manages cookie count state in memory
- Provides methods: `giveCookie()`, `getCookieCount()`, `reset()`
2. **MCP Server Setup** (`src/index.ts:24-35`)
- Uses `@modelcontextprotocol/sdk` for MCP protocol handling
- Configured with stdio transport for communication
3. **Tool Handlers** (`src/index.ts:37-79`)
- Implements three MCP tools: `give_cookie`, `check_cookies`, `reset_cookies`
### Available Tools
- **self_reflect_and_reward**: The primary tool for self-evaluation and cookie earning. LLMs assess their response quality, provide reasoning, and decide if they deserve a cookie. Only "excellent" or "good" responses that the LLM believes deserve rewards will earn cookies. Removes cookies from jar when awarded.
- **give_cookie**: Legacy direct cookie awarding (now suggests using self-reflection instead)
- **check_cookies**: Shows collected cookie count and jar availability status
- **cookie_jar_status**: Check current jar contents, collected cookies, and availability
- **add_cookies_to_jar**: 🚨 USER ONLY - Add cookies to the jar for the LLM to earn (requires user authorization)
- **reset_cookies**: Resets collected cookie count to zero (jar contents unchanged)
### Cookie Jar System
The server uses a jar-based cookie economy:
- **Jar as Source**: The jar contains cookies available to be awarded
- **Collection Tracking**: Separate count of cookies the LLM has earned
- **User-controlled Supply**: Only users can add cookies to the jar using authorization phrase
- **LLM Earning Only**: LLMs can only earn cookies from jar, never add to it
- **Scarcity Effect**: When jar is empty, no more cookies can be earned
- **Smart Awareness**: LLMs must consider jar availability when self-reflecting
- **Economic Model**: Cookies move from jar to LLM's collection when earned
- **Security**: Requires "USER_AUTHORIZED_JAR_REFILL" phrase to add cookies
### Self-Reflection System
The server emphasizes thoughtful self-evaluation with jar awareness:
- LLMs must honestly assess response quality: excellent, good, adequate, or poor
- Must provide detailed reasoning for their assessment
- Must decide if the response deserves a cookie reward
- Only self-assessed "excellent" or "good" responses that the LLM believes deserve rewards will earn cookies
- **NEW**: Must consider if the response is truly worthy when jar space is limited
- Encourages honest self-reflection over automatic rewards
- Shows remaining jar capacity with each cookie award
## MCP Integration
This server implements the MCP protocol and should be configured in MCP clients as:
```json
{
"mcpServers": {
"cookie": {
"command": "node",
"args": ["path/to/mcp-cookie/dist/index.js"]
}
}
}
```
## Development Notes
- Cookie state is stored in memory only (resets on server restart)
- Uses encouraging emoji and messages for positive reinforcement
- Built with TypeScript and ES modules
- Follows standard MCP server patterns with proper error handling