{
  "markdown": "# Neemee MCP Client Library\n\nA TypeScript client library for connecting to Neemee MCP servers using the official Model Context Protocol SDK.\n\n## Overview\n\nThis library provides a convenient interface for interacting with Neemee personal knowledge management systems through the Model Context Protocol (MCP). It supports both HTTP and STDIO transport modes and includes full TypeScript support.\n\n## Installation\n\n```bash\nnpm install neemee-mcp\n```\n\n## Quick Start\n\n### HTTP Mode (Web Applications)\n\n```typescript\nimport { NeemeeClient } from 'neemee-mcp';\n\nconst client = new NeemeeClient({\n  transport: 'http',\n  baseUrl: 'https://neemee.app/mcp',\n  apiKey: 'your-api-key'\n});\n\nawait client.connect();\n\n// Create a note\nconst result = await client.tools.createNote({\n  content: 'My note content',\n  title: 'My Note'\n});\n\nconsole.log(result);\n\nawait client.disconnect();\n```\n\n### STDIO Mode (Direct Process Communication)\n\n```typescript\nimport { NeemeeClient } from 'neemee-mcp';\n\nconst client = new NeemeeClient({\n  transport: 'stdio'\n});\n\nawait client.connect();\n\n// Use same API as HTTP mode\nconst notes = await client.resources.listNotes();\nconsole.log(notes);\n\nawait client.disconnect();\n```\n\n## API Reference\n\n### NeemeeClient\n\nMain client class that provides access to tools and resources.\n\n#### Constructor Options\n\n```typescript\ninterface NeemeeClientOptions {\n  transport: 'http' | 'stdio';\n  baseUrl?: string;        // For HTTP mode\n  apiKey?: string;         // For authentication\n  timeout?: number;        // Request timeout in milliseconds\n}\n```\n\n#### Methods\n\n- `connect(): Promise<void>` - Connect to the server\n- `disconnect(): Promise<void>` - Disconnect from the server\n- `listAvailableTools(): Promise<any>` - List available MCP tools\n- `listAvailableResources(): Promise<any>` - List available MCP resources\n\n### Tools API\n\nAccess via `client.tools`:\n\n#### Notes\n\n```typescript\n// Create a note\nawait client.tools.createNote({\n  content: 'Note content',\n  title: 'Optional title',\n  url: 'Optional source URL',\n  notebook: 'Optional notebook name',\n  frontmatter: { /* Optional metadata */ }\n});\n\n// Update a note\nawait client.tools.updateNote({\n  id: 'note-id',\n  content: 'Updated content',\n  title: 'Updated title'\n});\n\n// Delete a note\nawait client.tools.deleteNote('note-id', true);\n\n// Search notes\nawait client.tools.searchNotes({\n  query: 'search terms',\n  notebook: 'notebook-name',\n  domain: 'example.com',\n  tags: 'tag1,tag2',\n  startDate: '2024-01-01',\n  endDate: '2024-12-31',\n  limit: 50\n});\n```\n\n#### Notebooks\n\n```typescript\n// Create a notebook\nawait client.tools.createNotebook('Notebook Name', 'Optional description');\n\n// Update a notebook\nawait client.tools.updateNotebook('notebook-id', 'New Name', 'New description');\n\n// Delete a notebook\nawait client.tools.deleteNotebook('notebook-id', true);\n\n// Search notebooks\nawait client.tools.searchNotebooks('search query', 20);\n```\n\n### Resources API\n\nAccess via `client.resources`:\n\n#### Notes\n\n```typescript\n// List notes with filtering\nawait client.resources.listNotes({\n  page: 1,\n  limit: 20,\n  search: 'search terms',\n  domain: 'example.com',\n  notebook: 'notebook-name',\n  tags: 'tag1,tag2',\n  startDate: '2024-01-01',\n  endDate: '2024-12-31'\n});\n\n// Get a specific note\nawait client.resources.getNote('note-id');\n```\n\n#### Notebooks\n\n```typescript\n// List notebooks\nawait client.resources.listNotebooks({\n  page: 1,\n  limit: 20,\n  search: 'search terms'\n});\n\n// Get a specific notebook\nawait client.resources.getNotebook('notebook-id');\n```\n\n#### System Information\n\n```typescript\n// Get usage statistics\nawait client.resources.getStats();\n\n// Check system health\nawait client.resources.getHealth();\n\n// Get recent activity\nawait client.resources.getRecentActivity();\n```\n\n## Error Handling\n\nThe library provides specific error types for different failure scenarios:\n\n```typescript\nimport { \n  NeemeeClientError,\n  AuthenticationError,\n  ConnectionError,\n  NotFoundError,\n  ValidationError,\n  ServerError\n} from 'neemee-mcp';\n\ntry {\n  await client.connect();\n} catch (error) {\n  if (error instanceof AuthenticationError) {\n    console.error('Invalid API key');\n  } else if (error instanceof ConnectionError) {\n    console.error('Failed to connect to server');\n  } else if (error instanceof NeemeeClientError) {\n    console.error('Client error:', error.message);\n  }\n}\n```\n\n## Migration from v1.x\n\n### Breaking Changes\n\n- **Minimum Node.js version**: Now requires Node.js 18.0.0+\n- **Constructor options**: Format has changed (see Quick Start examples)\n- **Error types**: Updated error hierarchy\n- **Method signatures**: Some parameters refined for better type safety\n\n### Migration Guide\n\n#### Old v1.x Usage\n\n```typescript\n// v1.x (deprecated)\nconst client = new LegacyNeemeeClient({\n  useStdio: false,\n  serverUrl: 'https://api.example.com',\n  apiKey: 'key'\n});\n```\n\n#### New v2.x Usage\n\n```typescript\n// v2.x (recommended)\nconst client = new NeemeeClient({\n  transport: 'http',\n  baseUrl: 'https://api.example.com',\n  apiKey: 'key'\n});\n```\n\n#### Legacy Compatibility\n\nFor temporary compatibility, use the `LegacyNeemeeClient`:\n\n```typescript\nimport { LegacyNeemeeClient } from 'neemee-mcp';\n\n// This provides the old API while you migrate\nconst client = new LegacyNeemeeClient({\n  useStdio: false,\n  serverUrl: 'https://api.example.com',\n  apiKey: 'key'\n});\n```\n\n## Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/Paul-Bonneville-Labs/neemee-mcp.git\ncd neemee-mcp\nnpm install\nnpm run build\n```\n\n### Running Tests\n\n```bash\n# Test client functionality\nnpm run test:client\n\n# Test legacy compatibility\nnpm run test:legacy\n\n# Run with mock API server\nnpm run test:mock-api\n```\n\n### Available Scripts\n\n- `npm run build` - Compile TypeScript to dist/\n- `npm run dev` - Run development server with hot reload\n- `npm run test:client` - Test new client API\n- `npm run test:legacy` - Test legacy compatibility\n- `npm run test:integration` - Full integration tests\n\n## Examples\n\n### Complete Example with Error Handling\n\n```typescript\nimport { NeemeeClient, AuthenticationError, ConnectionError } from 'neemee-mcp';\n\nasync function example() {\n  const client = new NeemeeClient({\n    transport: 'http',\n    baseUrl: 'https://neemee.app/mcp',\n    apiKey: process.env.NEEMEE_API_KEY\n  });\n\n  try {\n    await client.connect();\n    \n    // Create a note\n    const createResult = await client.tools.createNote({\n      content: '# My First Note\\n\\nThis is some content.',\n      title: 'First Note',\n      frontmatter: {\n        tags: ['example', 'test'],\n        priority: 'high'\n      }\n    });\n    \n    console.log('Created note:', createResult);\n    \n    // Search for notes\n    const searchResult = await client.tools.searchNotes({\n      query: 'first',\n      tags: 'example',\n      limit: 10\n    });\n    \n    console.log('Found notes:', searchResult);\n    \n    // List available resources\n    const resources = await client.listAvailableResources();\n    console.log('Available resources:', resources);\n    \n  } catch (error) {\n    if (error instanceof AuthenticationError) {\n      console.error('Authentication failed - check your API key');\n    } else if (error instanceof ConnectionError) {\n      console.error('Connection failed - check server URL and network');\n    } else {\n      console.error('Unexpected error:', error);\n    }\n  } finally {\n    await client.disconnect();\n  }\n}\n\nexample().catch(console.error);\n```\n\n### Tag-Based Search\n\n```typescript\n// Search notes with multiple tags\nconst taggedNotes = await client.tools.searchNotes({\n  tags: 'work,important,urgent',\n  notebook: 'Projects',\n  limit: 25\n});\n\n// List notes with specific tags via resources\nconst resourceNotes = await client.resources.listNotes({\n  tags: 'research,ai',\n  domain: 'arxiv.org',\n  limit: 50\n});\n```\n\n## Configuration\n\n## Claude Desktop Configuration\n\nUse this package as a local bridge for STDIO transport:\n\n```json\n{\n  \"mcpServers\": {\n    \"neemee-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"neemee-mcp\", \"--api-key=your-api-key-here\"],\n      \"env\": {\n        \"NEEMEE_API_BASE_URL\": \"https://neemee.app/mcp\"\n      }\n    }\n  }\n}\n```\n\n**Authentication:** Uses API key authentication. Get your API key from Neemee settings. The API key can be provided via the `--api-key` flag in the `args` or as a `NEEMEE_API_KEY` environment variable.\n\n### Environment Variables\n\n- `NEEMEE_API_KEY` - Your Neemee API key (required for STDIO mode)\n- `NEEMEE_API_BASE_URL` - Base URL for Neemee API (defaults to https://neemee.app/mcp)\n\n### Authentication Scopes\n\nThe client supports different permission levels based on your API key:\n\n- **read**: Access to resources and search operations\n- **write**: Create and update operations (includes read)\n- **admin**: Delete operations (includes write and read)\n\n## TypeScript Support\n\nThis library is written in TypeScript and provides full type definitions:\n\n```typescript\nimport type { \n  NeemeeClientOptions,\n  CreateNoteParams,\n  UpdateNoteParams,\n  SearchNotesParams \n} from 'neemee-mcp';\n\nconst options: NeemeeClientOptions = {\n  transport: 'http',\n  baseUrl: 'https://api.example.com',\n  apiKey: 'your-key'\n};\n\nconst noteParams: CreateNoteParams = {\n  content: 'Note content',\n  title: 'Note title',\n  frontmatter: {\n    tags: ['typescript', 'example'],\n    date: new Date().toISOString()\n  }\n};\n```\n\n## License\n\nMIT\n\n## Support\n\n- GitHub Issues: [Report bugs and request features](https://github.com/Paul-Bonneville-Labs/neemee-mcp/issues)\n- Documentation: [Full API documentation](https://github.com/Paul-Bonneville-Labs/neemee-mcp#readme)",
  "bytes": 9594,
  "sha": "8217a8113eee1f4fd40a42d1d5a8e7865985b4f8571213ca579e7afe086943f0",
  "repo_slug": "paul-bonneville-labs/neemee-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pbonneville_neemee_mcp_782ec939/readme"
}