bereniketech/aios-connect

AIOS Connect

---

1. Input

Triggered with: /aios-connect <tool> or "connect me to <tool>".

If no tool given, read context/connections.md and recommend the highest-priority unwired bucket: Tasks → Calendar → Comms → Revenue → Customer → Meetings → Knowledge.

---

2. Decide API vs. MCP

Load .kit/skills/ai-platform/api-vs-mcp-decision/SKILL.md and apply its decision tree.

Key rules:

• 1–2 known endpoints → direct API call
• Need to discover available operations → MCP server
• MCP exists but context budget is tight (>5 MCPs already loaded) → direct API

State the decision and reason in one sentence before proceeding.

---

3. Research the API

Use WebSearch to find: auth method, base URL, rate limits, and the 5 most useful endpoints for AIOS use cases (read tasks, read events, read messages, read metrics, read files). Prefer official docs over community posts.

---

4. Write Reference Doc

Create context/api-<tool>.md:

# <Tool> API Reference

## Auth
- Type: [OAuth2 / API key / service account / PAT]
- Env var: [VAR_NAME]
- Setup: [one-line steps to get the key]

## Rate Limits
- [requests/min or requests/day]

## Key Endpoints

### [Endpoint name]
GET https://api.example.com/v1/endpoint
Authorization: Bearer $VAR_NAME

Response: [what it returns in one line]

[repeat for up to 4 more endpoints]

## AIOS Use Cases
- Read today's tasks: [endpoint + key params]
- Check latest event: [endpoint + key params]

---

5. Scaffold Wrapper

If the project has a lib/ directory, create lib/aios/<tool>.ts (adjust extension for project language):

export async function get<Tool>Data(params: Record<string, string> = {}) {
  const url = new URL("https://api.example.com/v1/endpoint");
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.TOOL_API_KEY}` },
  });
  if (!res.ok) throw new Error(`<Tool> API ${res.status}: ${await res.text()}`);
  return res.json();
}

Rule: Wrappers are read-only by default. Write operations are added only when explicitly requested.

---

6. Test the Connection

Make one read-only call. Report:

Connection test — <tool>
Endpoint: [what was called]
Status: [200 OK / error code]
Sample: [first field or item from response]

If the test fails, diagnose (wrong key, missing scope, wrong endpoint version) and fix before updating connections.md.

---

7. Update connections.md

Update the relevant row in context/connections.md:

| Field | Value | |---|---| | Status | live if test passed · partial if test failed | | Access method | lib/aios/<tool>.ts · or direct API · or MCP: <server-name> |

---

8. Completion

<Tool> connected.
Reference: context/api-<tool>.md
Wrapper:   lib/aios/<tool>.ts
Status:    live (test passed)

connections.md — [Bucket] bucket marked live.
Next: /aios-cadence to use this connection in a scheduled task.