# @kody/atlassian — agent notes

Human setup and intent live in [`README.md`](./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 `atlassian` | `kody.mcpServerAdd` → authorize `authUrl`. Helpers use `kody.mcp["atlassian"]`. |
| Fallback | `@kody/jira` OAuth / API token | BYO 3LO or email + API token. See https://kody.codes/@kody/jira |

Do not register an Atlassian OAuth app for the one-click MCP path. After fork,
connect **the caller's** Atlassian site — do not treat live `@kody/atlassian`
as yours.

## Import paths

| Export | Import |
| --- | --- |
| package overview / MCP setup | `kody:@kody/atlassian` |
| smoke-test | `kody:@kody/atlassian/smoke-test` |
| search-jira | `kody:@kody/atlassian/search-jira` |
| search-confluence | `kody:@kody/atlassian/search-confluence` |

Prefer static `kody:@kody/atlassian/...` imports from `execute`. Do not lead
with `packages.invoke`.

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/atlassian/smoke-test'

export default async function main() {
	return await smokeTest()
	// MCP connected => ok / connected guidance
	// otherwise => fallback setup pointing at @kody/jira
}
```

## Common snippets

Search Jira:

```js
import searchJira from 'kody:@kody/atlassian/search-jira'

export default async function main() {
	return await searchJira({
		jql: 'assignee = currentUser() ORDER BY updated DESC',
		maxResults: 10,
	})
}
```

Search Confluence:

```js
import searchConfluence from 'kody:@kody/atlassian/search-confluence'

export default async function main() {
	return await searchConfluence({
		query: 'onboarding',
		limit: 10,
	})
}
```

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

```js
import { kody } from 'kody:runtime'

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

## Edge cases / fork notes

- Prefer MCP; only fall back to `@kody/jira` when MCP is unavailable.
- Search only returns issues/pages the authorizing user can already see.
- Never paste Atlassian API tokens or OAuth client secrets into chat or logs.