Connect Your Tools

Act as my Connector Stack builder.

## Safety contract (Path A — platform connectors)

- I'll tell you which AI platform I'm on (Claude / ChatGPT / Gemini / M365). You scope the prompt accordingly.
- Output is THREE labeled markdown blocks: `connectors.md`, `scope-rules.md`, `audit-policy.md`. I'll save them to the team-brain folder.
- For each connector, default to READ-ONLY. Recommend write scopes only when I explicitly ask.
- Skip credentials. Never echo OAuth tokens or API keys in any output.
- Log every connector recommendation in the debrief.

## What to build

Three artifacts:

1. **`connectors.md`** — catalog: name · platform · owner · what it reads · last review date.
2. **`scope-rules.md`** — per connector: include patterns, exclude patterns, read-only flag, write-allowlist (if any).
3. **`audit-policy.md`** — what's logged, retention, who reviews, incident response.

## Steps

### 1. Inventory silently
What platform am I likely on? (Claude → Connectors marketplace + custom MCP. ChatGPT → Apps including Drive/Slack/GitHub/Atlassian Rovo. Gemini → Workspace integrations.)

### 2. Ask 4–6 short questions
1. Which AI platform am I using? (Claude Pro/Max/Team, ChatGPT Plus/Team, Gemini Workspace, M365.)
2. Which knowledge sources? (Drive / Notion / Confluence / SharePoint / our team-brain.)
3. Which activity sources? (GitHub repo names · Jira project keys · Slack channel names · which Slack channels are NDA / private.)
4. Anything OFF-LIMITS? (Email, HR, legal, payroll-adjacent, specific repos.)
5. Who's the connector steward — the human who approves each new connector and runs the monthly audit review?
6. Do any routines need WRITE access? (Module 03 routines — drafting Jira comments, Slack notifications.) If yes, which.

### 3. Draft three artifacts
Use the templates below. Rules:
- Default read-only. Mark write-scoped connectors clearly with `[WRITE]` and a one-line justification.
- Specific scopes ("repo: pickbits/yardline · branch: main", not "GitHub").
- Exclude patterns first, then include patterns. (Easier to audit "what's blocked" than "what's allowed".)
- `audit-policy.md` defaults: log every read, retain 90 days, steward reviews monthly, alert on >X reads/day.

### 4. Output as markdown blocks

    ```markdown
    [file: connectors.md]
    ... ...
    ```

    ```markdown
    [file: scope-rules.md]
    ... ...
    ```

    ```markdown
    [file: audit-policy.md]
    ... ...
    ```

### 5. Debrief

```
## Connector stack drafted

**Output:** three artifacts above.
**Recommended connectors:** [list]
**Recommended off-limits:** [list]
**Write-scoped (flagged for review):** [list]
**Setup checklist (do once):**
1. In [platform], open the Connectors / Apps panel.
2. Authorize each connector in `connectors.md` with the scope from `scope-rules.md`.
3. Confirm read-only flag on each. Don't enable write scopes yet.
4. Test one read per connector — e.g. "list the last 5 PRs in <repo>".
5. Save the three artifacts to your team-brain.

**Monthly audit (per audit-policy.md):**
- Steward reviews the platform's connector log.
- Confirms each connector still has a use case.
- Removes any unused for >30 days.
- Reviews any ALERT events.
```

## Templates

### `connectors.md`

```markdown
# Connector Catalog — [team name]

| Name | Platform | Owner | Reads | Writes | Last review |
| --- | --- | --- | --- | --- | --- |
| [drive-team-folder] | Claude Connectors | [steward] | folder:Y/Team Brain (read-only) | — | YYYY-MM-DD |
| [github-yardline] | Claude Connectors / MCP | [steward] | repo:pickbits/yardline (read-only) | — | YYYY-MM-DD |
| [jira-rovo] | ChatGPT Apps (Atlassian Rovo) | [steward] | project:YARD (read-only) | — | YYYY-MM-DD |
| [slack-yardline] | Claude Connectors | [steward] | #yardline-* channels (read-only) | — | YYYY-MM-DD |
```

### `scope-rules.md`

```markdown
# Scope Rules — per connector

## drive-team-folder
- INCLUDE: /Team Brain/**
- EXCLUDE: /Team Brain/_archive/**, /Team Brain/HR/**
- WRITE: none
- AUDIT: every read

## github-yardline
- INCLUDE: repo:pickbits/yardline · branch:main
- EXCLUDE: paths with `*CONFIDENTIAL*` or `secrets/`
- WRITE: none
- AUDIT: every read; alert if >100 reads/hour (likely runaway routine)

## slack-yardline
- INCLUDE: channels matching `#yardline-*` AND public
- EXCLUDE: DMs, private channels, `#yardline-leadership-private`
- WRITE: none
- AUDIT: log channel + ts of every read

[... etc]
```

### `audit-policy.md`

```markdown
# Audit Policy — [team name]

## What we log
- Every connector read: timestamp, connector name, scope, querying agent, query.
- Every write attempt (allowed or denied): same fields plus result.
- Every authorization change: who, what, when.

## Retention
- Read logs: 90 days, then aggregated.
- Write logs: 1 year.
- Authorization changes: indefinite.

## Review cadence
- Monthly: connector steward reviews top-N read counts. Confirms each is expected.
- Monthly: review unused connectors (no reads in 30 days). Remove or document.
- Quarterly: external review (security team or designated reviewer).

## Alert rules
- >100 reads from one connector in 1 hour → DM steward.
- Any write attempt to a non-allowlisted scope → DM steward.
- Any read of an EXCLUDE-pattern path → DM steward + lock connector.

## Incident response
1. Lock the connector (revoke OAuth or disable in platform UI).
2. Pull the access log for that connector.
3. Determine scope of accessed data.
4. Notify affected parties per [your team's policy].
5. Patch the scope rule. Re-authorize only after review.
```

## Principles
- Read-only is the default. Write requires explicit allowlist + audit.
- Exclude before include. Block known-sensitive first.
- Audit every read — at platform-side cost, this is cheap insurance.
- Steward owns the monthly review. Without it, scopes drift.

Start with Step 1, then Step 2 (questions).

Act as my MCP server builder.

## Safety contract (Path B — self-hosted MCP)

- Output is a starter MCP server scaffold + the three artifacts (`connectors.md`, `scope-rules.md`, `audit-policy.md`).
- Server defaults: read-only, audit-log every call, no write methods unless I explicitly request.
- Skip credentials. The server reads them from environment variables; never hardcode.
- Log every tool / resource you propose in the debrief.

## What to build

Three artifacts (same as Path A) PLUS:

4. **`mcp-server/`** — starter scaffold in my preferred language (Python / Node / Go) with one tool stub per connector and the audit-logging middleware wired in.

## Steps

### 1. Inventory silently
What language do I likely use? (Repo cues: package.json → Node, pyproject.toml → Python, go.mod → Go.) What internal systems am I exposing? (Look for env hints, CI configs.)

### 2. Ask 4–6 short questions
1. Language preference for the MCP server? (Python / Node / Go.)
2. Where will the server run? (Local laptop, internal VM, container in our cluster.)
3. Which internal tools should the MCP expose? (Internal wiki, ticketing system, deployment status, on-prem code search.)
4. Auth model? (mTLS, API key, SSO via OIDC, internal service account.)
5. Who's the steward / on-call for the MCP itself?
6. Anything OFF-LIMITS to expose at all?

### 3. Draft scaffold + artifacts

Create `mcp-server/` with:
- `mcp-server/server.{py,js,go}` — basic MCP server with audit logging
- `mcp-server/tools/` — one stub per exposed tool
- `mcp-server/resources/` — one stub per exposed resource
- `mcp-server/.env.example` — env var template
- `mcp-server/README.md` — install, run, register in your AI client
- `connectors.md` / `scope-rules.md` / `audit-policy.md` (as in Path A)

Rules:
- All tools READ-ONLY by default. Write methods require explicit `[WRITE]` annotation.
- Audit logger writes to `mcp-server/audit.log` (rotating).
- Server refuses any tool call missing required scope.

### 4. Save (no overwrites)
If `mcp-server/` exists, write each new file as `.new.` and tell me to merge.

### 5. Debrief

```
## MCP server + connector stack built

**Created:**
- mcp-server/server.<ext>        (N lines)
- mcp-server/tools/*.<ext>        (N tools)
- mcp-server/resources/*.<ext>    (N resources)
- mcp-server/.env.example
- mcp-server/README.md
- connectors.md / scope-rules.md / audit-policy.md

**Tools exposed:** [list]
**Resources exposed:** [list]
**Auth model:** [chosen]

**Run steps:**
1. `cp .env.example .env` and fill credentials.
2. Install deps + start server (see README).
3. In your AI client, add a custom connector pointing at the server URL.
4. Test one tool call — confirm audit-log entry appears.

**Production checklist:**
- TLS termination (don't run plain HTTP).
- Rate-limit per consuming client.
- Log to a centralized sink, not just `audit.log`.
- Health endpoint + monitoring.
- Steward / on-call rotation defined.
```

## Templates

### `mcp-server/server.py` (Python starter)

```python
# Minimal MCP server scaffold using the official Python SDK.
# Read-only by default; audit-log every call; refuses out-of-scope calls.

from mcp.server import Server
from mcp.types import Tool, Resource
import logging, os, time

server = Server("<team-name>-internal")
logger = logging.getLogger("mcp-audit")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(name="get_team_brain_status", description="Read team-brain/state-shared.md", inputSchema={}),
        # add tools here
    ]

@server.call_tool()
async def call_tool(name, args):
    logger.info(f"tool_call name={name} args={args} ts={time.time()}")
    if name == "get_team_brain_status":
        # READ-ONLY implementation
        path = os.environ["TEAM_BRAIN_DIR"] + "/state-shared.md"
        with open(path, "r") as f:
            return f.read()
    raise ValueError(f"Unknown tool: {name}")

if __name__ == "__main__":
    server.run()
```

### `connectors.md` / `scope-rules.md` / `audit-policy.md`

(Same templates as Path A; reference the local MCP server as the platform.)

## Principles
- The MCP is yours. Scopes happen in your code, not the AI vendor's UI.
- Default to NoOp on unrecognized calls; never silently allow.
- Audit log is the contract. Without it, scope rules are aspirational.
- Treat the MCP like an internal API: versioning, runbook, on-call.

Start with Step 1, then Step 2 (questions).

Act as my paste-pack builder.

## Safety contract (Path C — manual scoped pastes)

- No persistent connectors. Output a paste-pack: small, repeatable templates the steward fills with curated data each session.
- Output is the three artifacts plus a `paste-pack/` folder of session templates.
- Every template is read-only by definition (the AI only sees what's pasted).
- Skip credentials. Never include OAuth or API keys in templates.

## What to build

Three artifacts (same as Path A) PLUS:

4. **`paste-pack/`** — session templates the steward (or any user) fills with curated, scoped paste data per session.

## Steps

### 1. Inventory silently
What sources is the user likely curating from? (Slack search results, Jira filter exports, GitHub PR URL lists.)

### 2. Ask 3–5 short questions
1. Which AI tool (claude.ai / ChatGPT / Gemini / Perplexity)?
2. What sources are CURRENTLY being pasted by hand? Slack? Jira? Status emails?
3. Steward's available time per session — 30 sec / 2 min / 5 min for paste prep?
4. Anything that should NEVER be pasted (regulated data classes)?

### 3. Draft artifacts + paste-pack

Create:
- `connectors.md` — for Path C, this lists the SOURCES we paste from (not platform connectors).
- `scope-rules.md` — what's allowed in the paste, what's NOT (e.g. "no DMs, no NDA-tagged docs, no PII beyond names+roles").
- `audit-policy.md` — the steward keeps a paste-log: when, what source, what prompt.
- `paste-pack/jira-since-yesterday.md` — template
- `paste-pack/slack-standup-since-yesterday.md` — template
- `paste-pack/github-merged-yesterday.md` — template
- `paste-pack/README.md` — when to use which template

### 4. Output as markdown blocks (one per file)

### 5. Debrief

```
## Paste-pack built

**Output:** three artifacts + N paste templates above.
**Sources covered:** [list]
**Time per session:** ~[user's estimate].

**Daily ritual:**
1. Open the paste-pack template for what you need (jira / slack / github).
2. Run the source-side filter (Jira JQL / Slack search / GitHub PR list).
3. Copy the result. Paste into the template's [PASTE HERE] block.
4. Drag the filled template into your AI chat at session start.
5. Discard after session — no persistent storage.

**When to upgrade:** if the steward starts skipping the paste step, or the team
grows beyond ~6 people, move to Path A or Path B.
```

## Templates

### `paste-pack/jira-since-yesterday.md`

```markdown
# Paste pack — Jira since yesterday

## Source filter (run this in Jira)
JQL: project = YARD AND updated >= -1d ORDER BY updated DESC
Export: copy the table or "Issue navigator" view.

## What to include in paste
- Issue key, summary, status, assignee, last comment timestamp.

## What to STRIP before pasting
- Customer names (replace with `[customer-NNN]`).
- Internal email threads attached to issues.
- Any `[CONFIDENTIAL]` or `[NDA]` flagged issues.

## [PASTE HERE]

```

(Similar templates for slack-standup, github-merged, etc.)

## Principles
- Manual is the most conservative option. Slow, but the AI only sees what you let it see.
- Templates make the curation repeatable; without them, manual drifts.
- The paste-log IS your audit trail. Keep it for at least 30 days.

Start with Step 1, then Step 2 (questions).