@kody/notion-mcp

Search Notion through the official Notion MCP server.

AGENTS.md

74 lines · 2.2 KB · Markdown

@kody/notion-mcp — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke checks, snippets, and edge cases. Never paste tokens. Do not disable live webhooks or jobs.

Auth

Lane	Credential	Notes
Preferred	MCP server `notion`	`kody.mcpServerAdd` → authorize `authUrl`. Helpers use `kody.mcp["notion"]`.
Fallback	`@kody/notion` OAuth / API	BYO OAuth or API-key helpers. See https://kody.codes/@kody/notion

Do not register a Notion OAuth app for the one-click MCP path. After fork, connect the caller's Notion workspace — do not treat live @kody/notion-mcp as yours. MCP server name stays notion; -mcp is only the Kody package id.

Import paths

Export	Import
package overview / MCP setup	`kody:@kody/notion-mcp`
smoke-test	`kody:@kody/notion-mcp/smoke-test`
search	`kody:@kody/notion-mcp/search`

Prefer static kody:@kody/notion-mcp/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

import smokeTest from 'kody:@kody/notion-mcp/smoke-test'

export default async function main() {
	return await smokeTest()
	// MCP connected => { ok: true, live: true, via: 'mcp', ... }
	// otherwise => { ok: true, live: false, setup: { mcp, oauthApiFallback } }
}

Common snippets

Search Notion:

import searchNotion from 'kody:@kody/notion-mcp/search'

export default async function main() {
	return await searchNotion({ query: 'roadmap' })
}

Add MCP server (setup, not a package export):

import { kody } from 'kody:runtime'

export default async function main() {
	return await kody.mcpServerAdd({
		name: 'notion',
		url: 'https://mcp.notion.com/mcp',
	})
	// open returned authUrl, then retry smoke-test / search
}

Edge cases / fork notes

This package is MCP-only; OAuth/API-token work belongs in @kody/notion.
Search only returns pages the authorizing user can already see.
Helpers try several MCP tool name variants (search, notion-search, API-post-search); missing tools surface as setup errors, not silent empties.
Never paste Notion API tokens or OAuth client secrets into chat or logs.