improved-notion-mcp 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# Improved Notion MCP Server
+
+An enhanced Notion MCP server with better markdown conversion and composite tools for AI agents.
+
+## Features
+
+- **Token Optimization** - All read operations return markdown instead of raw JSON (~80% token reduction)
+- **Composite Tools** - Batch operations, append content, create pages with content in one call
+- **Full Notion API Coverage** - Search, CRUD operations, database queries, user listing
+- **TypeScript** - Full type safety and modern tooling
+
+## Installation
+
+```bash
+npm install improved-notion-mcp
+```
+
+## Configuration
+
+Set your Notion API token:
+
+```bash
+export NOTION_TOKEN=your_notion_integration_token
+```
+
+Or use `NOTION_API_KEY` as an alternative.
+
+## Usage
+
+### CLI
+
+```bash
+npx improved-notion-mcp
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "improved-notion-mcp": {
+      "command": "npx",
+      "args": ["-y", "improved-notion-mcp"],
+      "env": {
+        "NOTION_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "improved-notion-mcp": {
+      "command": "npx",
+      "args": ["-y", "improved-notion-mcp"],
+      "env": {
+        "NOTION_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Search & Discovery
+- `notion_search` - Search pages and databases
+- `notion_list_databases` - List all accessible databases
+- `notion_list_users` - List workspace users
+
+### Read Operations (Token-Optimized)
+- `notion_get_page` - Get page content as markdown (~80% fewer tokens)
+- `notion_get_database_schema` - Get database schema/properties
+- `notion_query_database` - Query database with filters
+
+### Write Operations
+- `notion_create_page` - Create a new page (optionally with content)
+- `notion_create_database_entry` - Create database entry
+- `notion_update_page` - Update page properties or content
+- `notion_append_content` - Append markdown to existing page
+
+### Batch Operations
+- `notion_batch_create` - Create multiple pages at once
+
+### Delete Operations
+- `notion_delete_page` - Archive a page
+
+## Token Optimization
+
+The official Notion MCP returns raw JSON from the API, which includes lots of metadata that AI agents don't need. This server:
+
+1. Converts all page content to markdown
+2. Formats properties as readable key-value pairs
+3. Strips unnecessary metadata
+
+**Result**: ~80% reduction in token usage for typical operations.
+
+## Comparison
+
+| Feature | Official Notion MCP | This Server |
+|---------|-------------------|-------------|
+| Token usage | High (raw JSON) | Low (markdown) |
+| Composite tools | Limited | Batch create, append |
+| Block types | 15 | 20+ |
+| Tools | ~20 auto-generated | 12 focused |
+
+## Development
+
+```bash
+npm run dev    # Development mode
+npm run build  # Build for production
+npm start      # Run production build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}