# Pullnote

> Pullnote is a cloud-based headless API that provides a simple database to store and retrieve content using NPM, REST, or MCP Server integration. It eliminates the need to build a content backend for each project by offering a centralized content management system with an optional human editor interface at pullnote.com.

Pullnote is designed for developers who need a lightweight, API-first content management solution. It supports both programmatic content creation and human editing through a web interface. The service includes AI-powered content generation capabilities and provides multiple integration methods including a JavaScript client library, REST API, and MCP server for LLM tools.

## Installation and Setup

```javascript
npm install @pullnote/client
import { PullnoteClient } from '@pullnote/client';
const pn = new PullnoteClient('YOUR_API_KEY');
```

## Core API Methods

### Basic CRUD Operations

```javascript
// Create a note
await pn.add('/path/to/note', {
    title: 'Note Title',
    content: 'Markdown content here',
    description: 'Optional description',
    imgUrl: 'https://example.com/image.png'
});

// Retrieve a note
const note = await pn.get('/path/to/note');
const title = await pn.getTitle('/path/to/note');
const htmlContent = await pn.getHtml('/path/to/note');
const markdownContent = await pn.getMd('/path/to/note');

// Update a note
await pn.update('/path/to/note', { title: 'Updated Title' });

// Delete a note
await pn.remove('/path/to/note');
```

### AI-Powered Content Generation

```javascript
// Generate content using AI prompts
await pn.add('/ai-generated-note', {
    title: 'AI Generated Content',
    prompt: 'Write a short article about the benefits of cloud computing',
    imgPrompt: 'Generate an image representing cloud technology'
});
```

### Hierarchical Navigation

```javascript
// Get surrounding notes (useful for building menus)
const surrounding = await pn.list('/blog');
// Returns: { self, parent, parents[], children[], siblings[], index }

// Get specific relationships
const parent = await pn.getParent('/blog/post-1');
const children = await pn.getChildren('/blog');
const siblings = await pn.getSiblings('/blog/post-1');
const breadcrumbs = await pn.getBreadcrumbs('/blog/post-1');
```

### Metadata and SEO

```javascript
// Get SEO-friendly head tags
const head = await pn.getHead('/blog/post-1');
// Returns: { title, description, imgUrl }

// Work with custom data
await pn.setData('/blog/post-1', { 
    locale: 'en-US', 
    category: 'technology',
    product_id: 'PROD123'
});
const data = await pn.getData('/blog/post-1');
```

## Note Structure

```typescript
interface Note {
  _id: string;
  project_id: string;
  path: string;           // e.g. "blog/cats"
  title: string;
  description?: string;
  imgUrl?: string;        // Your URL or Pullnote hosted
  prompt?: string;        // AI prompt for content generation
  imgPrompt?: string;     // AI prompt for image generation
  content?: string;       // Raw markdown content
  created: string;        // ISO date string
  modified: string;       // ISO date string
  author?: string;        // Display name
  data?: Record<string, any>; // Custom JSON metadata
  index?: number;         // Custom ordering
}
```

## MCP Server Integration

For LLM tools like Cursor and Claude Code:

```json
{
  "mcpServers": {},
  "remoteServers": {
    "pullnote-api": {
      "url": "https://api.pullnote.com/mcp?key=[YOUR_API_KEY]"
    }
  }
}
```

### MCP Request Format

```json
{
  "action": "create|retrieve|update|delete|list",
  "tool": "note",
  "params": {
    "title": "Note Title",
    "content": "Content here",
    "prompt": "AI prompt (optional)",
    "imgPrompt": "Image prompt (optional)"
  },
  "pullnote_key": "YOUR_API_KEY"
}
```

## Common Use Cases

### Building a Blog Menu
```javascript
const blogStructure = await pn.list('/blog');
const menuItems = blogStructure.children.map(child => ({
    title: child.title,
    path: child.path,
    description: child.description
}));
```

### Creating SEO Pages
```javascript
const note = await pn.get('/product-page');
const head = await pn.getHead('/product-page');
// Use head.title, head.description, head.imgUrl for meta tags
```

### Batch Content Creation
```javascript
const articles = [
    { path: '/blog/article-1', title: 'First Article', prompt: 'Write about AI' },
    { path: '/blog/article-2', title: 'Second Article', prompt: 'Write about ML' }
];

for (const article of articles) {
    await pn.add(article.path, {
        title: article.title,
        prompt: article.prompt
    });
}
```

## External Resources

- [NPM Repository](https://github.com/webuildsociety/pullnote): Repository and source code for the client NPM package
- [Pullnote Website](https://pullnote.com): Account management and human editor
- [API Pricing](https://pullnote.com/pricing): Usage limits and pricing
- [OpenAPI Spec](https://api.pullnote.com/openapi.json): Machine-readable API specification