@backendkit-labs/mcp-connectors 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,743 @@
+# @backendkit-labs/mcp-connectors
+
+> **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
+
+Three production-ready MCP (Model Context Protocol) servers that expose enterprise SaaS integrations as agent tools: **HubSpot CRM**, **Jira**, and **Google Calendar**.
+
+Each connector ships as a standalone binary that runs in stdio mode (for use with any MCP client) or HTTP mode (for multi-tenant server deployments).
+
+[![npm](https://img.shields.io/npm/v/@backendkit-labs/mcp-connectors)](https://www.npmjs.com/package/@backendkit-labs/mcp-connectors)
+
+## Table of contents
+
+- [Installation](#installation)
+- [Running the servers](#running-the-servers)
+- [HubSpot CRM connector](#hubspot-crm-connector)
+- [Jira connector](#jira-connector)
+- [Google Calendar connector](#google-calendar-connector)
+- [Using with agent-core MCPClientManager](#using-with-agent-core-mcpclientmanager)
+- [HTTP mode (multi-session)](#http-mode-multi-session)
+- [Wiring all three connectors](#wiring-all-three-connectors)
+
+---
+
+## Installation
+
+```bash
+npm install @backendkit-labs/mcp-connectors
+```
+
+The package ships three binaries:
+
+| Binary | MCP server name |
+|--------|----------------|
+| `bk-mcp-hubspot` | `bk-mcp-hubspot` |
+| `bk-mcp-jira` | `bk-mcp-jira` |
+| `bk-mcp-gcal` | `bk-mcp-gcal` |
+
+Or use via `npx` without installing:
+
+```bash
+npx @backendkit-labs/mcp-connectors bk-mcp-hubspot
+```
+
+---
+
+## Running the servers
+
+### Stdio mode (default — for MCP clients like Claude Desktop, agent-core)
+
+```bash
+# HubSpot
+HUBSPOT_TOKEN=pat-xxx bk-mcp-hubspot
+
+# Jira
+JIRA_HOST=mycompany.atlassian.net JIRA_EMAIL=me@co.com JIRA_TOKEN=xxx bk-mcp-jira
+
+# Google Calendar (service account — recommended)
+GCAL_SERVICE_ACCOUNT_KEY='{ "client_email": "...", "private_key": "..." }' bk-mcp-gcal
+
+# Google Calendar (access token — short-lived, for quick testing)
+GCAL_ACCESS_TOKEN=ya29.xxx bk-mcp-gcal
+```
+
+### HTTP mode (for remote/multi-session deployments)
+
+```bash
+bk-mcp-hubspot --http --port 4001
+bk-mcp-jira    --http --port 4002
+bk-mcp-gcal    --http --port 4003
+```
+
+---
+
+## HubSpot CRM connector
+
+### Authentication
+
+Create a **Private App** in your HubSpot account (`Settings → Integrations → Private Apps`), grant it the required CRM scopes, and copy the access token:
+
+| Environment variable | Required | Description |
+|---------------------|----------|-------------|
+| `HUBSPOT_TOKEN` | Yes | Private App access token |
+
+### Tools
+
+#### `crm_search_contacts`
+
+Search contacts by name, email, or company name.
+
+```
+Tool: crm_search_contacts
+Args:
+  query  string   Search term — name, email, or company
+  limit  number?  Max results (default 10)
+```
+
+**Example:**
+```
+search for alice@acme.com
+→ crm_search_contacts({ query: "alice@acme.com" })
+→ "ID:12345  Alice Johnson  <alice@acme.com>  Acme Corp  +1-555-0100"
+```
+
+**Complex example — search and enrich:**
+```
+Find all contacts at Acme Corp and tell me their job titles and when they were created
+→ crm_search_contacts({ query: "Acme Corp", limit: 50 })
+→ For each contact: crm_get_contact({ id: "..." })
+→ LLM synthesizes a table of names, titles, and creation dates
+```
+
+---
+
+#### `crm_get_contact`
+
+Get full property details for a contact by HubSpot ID.
+
+```
+Tool: crm_get_contact
+Args:
+  id  string  HubSpot contact ID
+```
+
+**Returns:** `firstname`, `lastname`, `email`, `phone`, `company`, `jobtitle`, `lifecyclestage`, `createdate`, `lastmodifieddate`
+
+**Example:**
+```
+Get the full details for contact 12345
+→ crm_get_contact({ id: "12345" })
+→ "Contact 12345
+   firstname: Alice
+   lastname: Johnson
+   email: alice@acme.com
+   jobtitle: VP Engineering
+   lifecyclestage: customer"
+```
+
+---
+
+#### `crm_create_contact`
+
+Create a new contact in HubSpot CRM.
+
+```
+Tool: crm_create_contact
+Args:
+  email     string   Email address (required)
+  firstname string?
+  lastname  string?
+  phone     string?
+  company   string?
+  jobtitle  string?
+```
+
+**Example:**
+```
+Add Bob Smith from Globex as a new CRM contact — bob@globex.com, +1-555-9999, Sr. Engineer
+→ crm_create_contact({
+    email:     "bob@globex.com",
+    firstname: "Bob",
+    lastname:  "Smith",
+    company:   "Globex",
+    phone:     "+1-555-9999",
+    jobtitle:  "Sr. Engineer"
+  })
+→ "Created contact ID: 67890"
+```
+
+---
+
+#### `crm_search_deals`
+
+Search deals by name and/or deal stage.
+
+```
+Tool: crm_search_deals
+Args:
+  query  string?  Deal name search term
+  stage  string?  Deal stage key (e.g. appointmentscheduled, qualifiedtobuy, closedwon, closedlost)
+  limit  number?  Max results (default 10)
+```
+
+**Example — find open deals:**
+```
+Show me all deals in the "Qualified to Buy" stage worth over $50k
+→ crm_search_deals({ stage: "qualifiedtobuy", limit: 50 })
+→ LLM filters by amount from results
+→ "ID:111  Enterprise License  stage:qualifiedtobuy  $75,000  close:2026-09-01"
+```
+
+**Example — search by name:**
+```
+Find the Acme Corp deal
+→ crm_search_deals({ query: "Acme Corp" })
+→ "ID:222  Acme Corp Enterprise  stage:presentationscheduled  $120,000  close:2026-07-15"
+```
+
+---
+
+#### `crm_create_note`
+
+Log an activity note, optionally linked to a contact and/or deal.
+
+```
+Tool: crm_create_note
+Args:
+  body        string   Note content
+  contact_id  string?  HubSpot contact ID to associate
+  deal_id     string?  HubSpot deal ID to associate
+```
+
+**Example:**
+```
+Log a call note: "Spoke with Alice, agreed to send proposal by Friday"
+Associate with contact 12345 and deal 222
+→ crm_create_note({
+    body:       "Spoke with Alice, agreed to send proposal by Friday",
+    contact_id: "12345",
+    deal_id:    "222"
+  })
+→ "Created note ID: 333"
+```
+
+**Complex workflow example:**
+
+```
+After our sales call with Acme Corp today:
+1. Find the Acme contact and deal
+2. Log a note about the meeting outcome
+3. Check if the deal close date needs updating
+
+→ crm_search_contacts({ query: "Alice Acme Corp" })     → contact 12345
+→ crm_search_deals({ query: "Acme Corp" })               → deal 222
+→ crm_create_note({ body: "...", contact_id: "12345", deal_id: "222" })
+→ LLM: "Note logged. The deal close date is 2026-07-15 — would you like to update it?"
+```
+
+---
+
+## Jira connector
+
+### Authentication
+
+Generate an **API token** at `https://id.atlassian.com/manage-profile/security/api-tokens`.
+
+| Environment variable | Required | Description |
+|---------------------|----------|-------------|
+| `JIRA_HOST` | Yes | Your Jira domain (e.g. `mycompany.atlassian.net`) |
+| `JIRA_EMAIL` | Yes | Your Atlassian account email |
+| `JIRA_TOKEN` | Yes | Jira API token (not your password) |
+
+### Tools
+
+#### `jira_search`
+
+Search Jira issues using JQL (Jira Query Language).
+
+```
+Tool: jira_search
+Args:
+  jql    string   JQL query
+  limit  number?  Max results (default 20)
+```
+
+**JQL examples:**
+```
+# All open bugs in PROJ, assigned to me
+jql: project = PROJ AND issuetype = Bug AND status != Done AND assignee = currentUser()
+
+# Recently updated critical issues
+jql: priority = Critical AND updated >= -7d ORDER BY updated DESC
+
+# Issues in the current sprint
+jql: project = PROJ AND sprint in openSprints()
+
+# My unresolved tasks due this week
+jql: assignee = currentUser() AND resolution = Unresolved AND due <= endOfWeek()
+```
+
+**Example:**
+```
+Show me all open bugs in the BACKEND project assigned to Alice
+→ jira_search({ jql: 'project = BACKEND AND issuetype = Bug AND status != Done AND assignee = "Alice Johnson"' })
+→ "BACK-45  [In Progress]  High  Auth token expiry bug  @Alice Johnson
+   BACK-51  [To Do]        Medium  Rate limit not enforced  @Alice Johnson"
+```
+
+---
+
+#### `jira_get_issue`
+
+Get full details for a Jira issue including description and recent comments.
+
+```
+Tool: jira_get_issue
+Args:
+  key  string  Issue key (e.g. PROJ-123)
+```
+
+**Returns:** summary, status, assignee, description (converted from ADF to plain text), last 3 comments.
+
+**Example:**
+```
+What's the current status and description of BACK-45?
+→ jira_get_issue({ key: "BACK-45" })
+→ "BACK-45: Auth token expiry bug
+   Status: In Progress   Assignee: Alice Johnson
+   
+   Description:
+   When a token expires during an active session, the server returns 500
+   instead of 401. Reproduction steps: ...
+   
+   Comments (last 2):
+     [Alice Johnson · 2026-06-10]: Traced to TokenValidator.validate()
+     [Bob Smith · 2026-06-11]: PR opened: https://..."
+```
+
+---
+
+#### `jira_create_issue`
+
+Create a new Jira issue.
+
+```
+Tool: jira_create_issue
+Args:
+  project      string   Project key (e.g. PROJ)
+  summary      string   Issue title
+  description  string?  Plain text description
+  issue_type   string?  Issue type (default: Task). E.g. Bug, Story, Epic
+  priority     string?  Priority (Highest, High, Medium, Low, Lowest)
+```
+
+**Example:**
+```
+Create a high-priority bug in BACK: "Login fails for SAML users with special characters in email"
+→ jira_create_issue({
+    project:     "BACK",
+    summary:     "Login fails for SAML users with special characters in email",
+    description: "Users with + in email address cannot log in via SAML SSO. Affects @company.com+alias emails.",
+    issue_type:  "Bug",
+    priority:    "High"
+  })
+→ "Created BACK-52 (ID: 100023)"
+```
+
+---
+
+#### `jira_add_comment`
+
+Add a comment to a Jira issue.
+
+```
+Tool: jira_add_comment
+Args:
+  key   string  Issue key
+  body  string  Comment text
+```
+
+**Example:**
+```
+Add a comment to BACK-45: "Fixed in PR #127, ready for review"
+→ jira_add_comment({ key: "BACK-45", body: "Fixed in PR #127, ready for review" })
+→ "Comment added to BACK-45."
+```
+
+---
+
+#### `jira_transition`
+
+Move an issue to a new status (e.g. move from "To Do" to "In Progress").
+
+```
+Tool: jira_transition
+Args:
+  key     string  Issue key
+  status  string  Target status name (e.g. Done, In Progress, To Do, In Review)
+```
+
+The tool fetches available transitions first and matches by name (case-insensitive). If the target status isn't available, it reports valid options.
+
+**Example:**
+```
+Mark BACK-52 as "In Progress"
+→ jira_transition({ key: "BACK-52", status: "In Progress" })
+→ "BACK-52 → "In Progress""
+
+Mark BACK-45 as done
+→ jira_transition({ key: "BACK-45", status: "Done" })
+→ "BACK-45 → "Done""
+```
+
+**Complex workflow — sprint management:**
+
+```
+Close out the sprint: mark all Done issues as closed, move remaining In Progress issues to next sprint
+
+→ jira_search({ jql: "sprint in openSprints() AND status = Done" })
+  For each: jira_transition({ key: "...", status: "Closed" })
+
+→ jira_search({ jql: "sprint in openSprints() AND status = 'In Progress'" })
+  LLM: "Found 3 in-progress issues: BACK-48, BACK-50, BACK-53. Move them to next sprint? (I need the sprint ID)"
+```
+
+---
+
+## Google Calendar connector
+
+### Authentication
+
+Two auth modes are supported, checked in order:
+
+#### Mode 1: Service Account (recommended for production)
+
+Create a service account in Google Cloud Console, download the JSON key, and share the target calendar with the service account email. Supports automatic token refresh — no manual intervention needed.
+
+```bash
+# Paste the full JSON content of the service account key file
+GCAL_SERVICE_ACCOUNT_KEY='{"type":"service_account","client_email":"bk-agent@my-project.iam.gserviceaccount.com","private_key":"-----BEGIN RSA PRIVATE KEY-----\n...","token_uri":"https://oauth2.googleapis.com/token"}'
+```
+
+The private key can also contain literal `\n` (as stored in environment variables) — the server handles unescaping automatically.
+
+#### Mode 2: Access Token (quick testing)
+
+```bash
+GCAL_ACCESS_TOKEN=ya29.a0AfH...   # Google OAuth2 access token (expires in ~1h)
+```
+
+| Environment variable | Required | Description |
+|---------------------|----------|-------------|
+| `GCAL_SERVICE_ACCOUNT_KEY` | Recommended | Full JSON content of a service account key |
+| `GCAL_ACCESS_TOKEN` | Alternative | Short-lived OAuth2 token |
+
+### Tools
+
+#### `calendar_list_calendars`
+
+List all Google Calendars accessible to the authenticated account.
+
+```
+Tool: calendar_list_calendars
+Args: (none)
+```
+
+**Example:**
+```
+What calendars do I have access to?
+→ calendar_list_calendars()
+→ "primary@company.com  "Alice Johnson" (primary)  [owner]
+   team-eng@group.calendar.google.com  "Engineering Team"  [writer]
+   company-holidays@group.calendar.google.com  "Company Holidays"  [reader]"
+```
+
+---
+
+#### `calendar_list_events`
+
+List upcoming events within a time range.
+
+```
+Tool: calendar_list_events
+Args:
+  calendar_id  string?  Calendar ID (default: "primary")
+  time_min     string?  Start of range, ISO 8601 (default: now)
+  time_max     string?  End of range, ISO 8601 (default: 7 days from now)
+  limit        number?  Max events (default 10)
+```
+
+**Example — this week:**
+```
+What's on my calendar this week?
+→ calendar_list_events({ limit: 20 })
+→ "[2026-06-11 09:00 – 09:30] Daily Standup
+   [2026-06-11 14:00 – 15:00] Architecture Review  (4 attendees)
+   [2026-06-12 10:00 – 11:00] 1:1 with Bob
+   [2026-06-13 All Day] Company Holiday"
+```
+
+**Example — specific calendar and range:**
+```
+Show me all Engineering Team events for next month
+→ calendar_list_events({
+    calendar_id: "team-eng@group.calendar.google.com",
+    time_min:    "2026-07-01T00:00:00Z",
+    time_max:    "2026-07-31T23:59:59Z",
+    limit:       50
+  })
+```
+
+---
+
+#### `calendar_create_event`
+
+Create a new event in Google Calendar.
+
+```
+Tool: calendar_create_event
+Args:
+  summary      string    Event title (required)
+  start        string    Start time ISO 8601 (required)
+  end          string    End time ISO 8601 (required)
+  description  string?   Event description
+  attendees    string[]? List of attendee email addresses
+  timezone     string?   IANA timezone (default: UTC)
+  calendar_id  string?   Calendar ID (default: "primary")
+```
+
+**Example — simple meeting:**
+```
+Schedule a 1-hour team sync tomorrow at 2pm Pacific
+→ calendar_create_event({
+    summary:  "Team Sync",
+    start:    "2026-06-12T14:00:00",
+    end:      "2026-06-12T15:00:00",
+    timezone: "America/Los_Angeles"
+  })
+→ "Event created: abc123def
+   https://calendar.google.com/calendar/event?eid=..."
+```
+
+**Example — meeting with attendees:**
+```
+Book a sprint planning meeting for next Monday 10am-12pm UTC
+Invite: alice@co.com, bob@co.com, carol@co.com
+Add agenda to description
+→ calendar_create_event({
+    summary:     "Sprint Planning — Q3 Sprint 2",
+    start:       "2026-06-15T10:00:00",
+    end:         "2026-06-15T12:00:00",
+    timezone:    "UTC",
+    description: "Agenda:\n1. Review previous sprint\n2. Story point estimation\n3. Sprint commitment",
+    attendees:   ["alice@co.com", "bob@co.com", "carol@co.com"]
+  })
+→ "Event created: xyz789
+   https://calendar.google.com/..."
+```
+
+---
+
+#### `calendar_get_freebusy`
+
+Check free/busy availability for one or more users in a time range.
+
+```
+Tool: calendar_get_freebusy
+Args:
+  emails    string[]  List of email addresses to check (required)
+  time_min  string    Start of range, ISO 8601 (required)
+  time_max  string    End of range, ISO 8601 (required)
+```
+
+**Example — find a meeting slot:**
+```
+Find a 1-hour slot when alice@co.com, bob@co.com, and carol@co.com are all free next Tuesday
+→ calendar_get_freebusy({
+    emails:   ["alice@co.com", "bob@co.com", "carol@co.com"],
+    time_min: "2026-06-16T08:00:00Z",
+    time_max: "2026-06-16T18:00:00Z"
+  })
+→ "alice@co.com:
+     BUSY 09:00 – 09:30
+     BUSY 11:00 – 12:00
+   bob@co.com: FREE all day
+   carol@co.com:
+     BUSY 10:00 – 11:30
+     BUSY 14:00 – 15:00"
+→ LLM: "Everyone is free from 12:00 to 14:00 and from 15:00 to 18:00. Should I book 12:00–13:00?"
+```
+
+---
+
+## Using with agent-core MCPClientManager
+
+### Stdio mode (local — recommended for development)
+
+```typescript
+import { MCPClientManager } from '@backendkit-labs/agent-core';
+
+const mcp = new MCPClientManager();
+
+await mcp.connectStdio({
+  name:    'hubspot',
+  command: 'bk-mcp-hubspot',
+  args:    [],
+  env:     { HUBSPOT_TOKEN: process.env.HUBSPOT_TOKEN! },
+});
+
+await mcp.connectStdio({
+  name:    'jira',
+  command: 'bk-mcp-jira',
+  args:    [],
+  env:     {
+    JIRA_HOST:  process.env.JIRA_HOST!,
+    JIRA_EMAIL: process.env.JIRA_EMAIL!,
+    JIRA_TOKEN: process.env.JIRA_TOKEN!,
+  },
+});
+
+await mcp.connectStdio({
+  name:    'gcal',
+  command: 'bk-mcp-gcal',
+  args:    [],
+  env:     { GCAL_SERVICE_ACCOUNT_KEY: process.env.GCAL_SERVICE_ACCOUNT_KEY! },
+});
+
+// All tools are now available to the engine
+const tools = mcp.getTools();
+```
+
+### Via engine options (recommended approach)
+
+Pass `mcpServers` to `createBaseEngine` or `createCodingEngine` — the engine manages lifecycle, retries, and disconnect detection:
+
+```typescript
+import { createBaseEngine } from '@backendkit-labs/agent-core';
+
+const engine = createBaseEngine({
+  ...baseConfig,
+  mcpServers: [
+    {
+      name:    'hubspot',
+      command: 'npx',
+      args:    ['-y', '@backendkit-labs/mcp-connectors/hubspot'],
+      env:     { HUBSPOT_TOKEN: process.env.HUBSPOT_TOKEN! },
+    },
+    {
+      name:    'jira',
+      command: 'npx',
+      args:    ['-y', '@backendkit-labs/mcp-connectors/jira'],
+      env:     {
+        JIRA_HOST:  process.env.JIRA_HOST!,
+        JIRA_EMAIL: process.env.JIRA_EMAIL!,
+        JIRA_TOKEN: process.env.JIRA_TOKEN!,
+      },
+    },
+    {
+      name:    'gcal',
+      command: 'npx',
+      args:    ['-y', '@backendkit-labs/mcp-connectors/gcal'],
+      env:     { GCAL_SERVICE_ACCOUNT_KEY: process.env.GCAL_SERVICE_ACCOUNT_KEY! },
+    },
+  ],
+});
+```
+
+---
+
+## HTTP mode (multi-session)
+
+Start the servers in HTTP mode when you want to share one connector instance across multiple agent sessions (e.g. in a containerized deployment):
+
+```bash
+# Start connectors as HTTP servers
+HUBSPOT_TOKEN=xxx bk-mcp-hubspot --http --port 4001
+JIRA_HOST=co.atlassian.net JIRA_EMAIL=me@co.com JIRA_TOKEN=xxx bk-mcp-jira --http --port 4002
+GCAL_SERVICE_ACCOUNT_KEY='...' bk-mcp-gcal --http --port 4003
+```
+
+Connect via `connectStreamableHTTP`:
+
+```typescript
+await mcp.connectStreamableHTTP({ name: 'hubspot', baseUrl: 'http://mcp-hubspot:4001' });
+await mcp.connectStreamableHTTP({ name: 'jira',    baseUrl: 'http://mcp-jira:4002' });
+await mcp.connectStreamableHTTP({ name: 'gcal',    baseUrl: 'http://mcp-gcal:4003' });
+```
+
+Docker Compose example:
+
+```yaml
+services:
+  mcp-hubspot:
+    image: node:20
+    command: ["npx", "-y", "@backendkit-labs/mcp-connectors", "bk-mcp-hubspot", "--http", "--port", "4001"]
+    environment:
+      HUBSPOT_TOKEN: ${HUBSPOT_TOKEN}
+    ports: ["4001:4001"]
+
+  mcp-jira:
+    image: node:20
+    command: ["npx", "-y", "@backendkit-labs/mcp-connectors", "bk-mcp-jira", "--http", "--port", "4002"]
+    environment:
+      JIRA_HOST:  ${JIRA_HOST}
+      JIRA_EMAIL: ${JIRA_EMAIL}
+      JIRA_TOKEN: ${JIRA_TOKEN}
+    ports: ["4002:4002"]
+
+  mcp-gcal:
+    image: node:20
+    command: ["npx", "-y", "@backendkit-labs/mcp-connectors", "bk-mcp-gcal", "--http", "--port", "4003"]
+    environment:
+      GCAL_SERVICE_ACCOUNT_KEY: ${GCAL_SERVICE_ACCOUNT_KEY}
+    ports: ["4003:4003"]
+```
+
+---
+
+## Wiring all three connectors
+
+Full example — an agent that can manage CRM contacts, Jira issues, and calendar events together:
+
+```typescript
+import { createCodingEngine } from '@backendkit-labs/agent-coding';
+
+const engine = createCodingEngine({
+  providers: {
+    deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
+  },
+  defaultProvider: 'deepseek',
+  mcpServers: [
+    {
+      name:    'hubspot',
+      command: 'bk-mcp-hubspot',
+      args:    [],
+      env:     { HUBSPOT_TOKEN: process.env.HUBSPOT_TOKEN! },
+    },
+    {
+      name:    'jira',
+      command: 'bk-mcp-jira',
+      args:    [],
+      env:     {
+        JIRA_HOST:  process.env.JIRA_HOST!,
+        JIRA_EMAIL: process.env.JIRA_EMAIL!,
+        JIRA_TOKEN: process.env.JIRA_TOKEN!,
+      },
+    },
+    {
+      name:    'gcal',
+      command: 'bk-mcp-gcal',
+      args:    [],
+      env:     { GCAL_SERVICE_ACCOUNT_KEY: process.env.GCAL_SERVICE_ACCOUNT_KEY! },
+    },
+  ],
+});
+
+// Multi-tool agent workflow
+await engine.run(`
+  I just closed the Acme Corp deal. Please:
+  1. Find the Acme Corp deal in HubSpot and log a note: "Deal closed — contract signed"
+  2. Create a Jira task in the ONBOARD project: "Onboard Acme Corp — enterprise tier"
+  3. Schedule a kickoff meeting for next Wednesday at 2pm ET with alice@acme.com
+`);
+```

package/dist/odoo/server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/odoo/server.d.ts.map

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

package/dist/odoo/server.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const server_runner_js_1 = require("../shared/server-runner.js");
+let _session = null;
+function cfg() {
+    const url = process.env.ODOO_URL?.replace(/\/$/, '');
+    const db = process.env.ODOO_DB;
+    const user = process.env.ODOO_USER;
+    const pass = process.env.ODOO_PASSWORD;
+    if (!url || !db || !user || !pass) {
+        throw new Error('Set ODOO_URL, ODOO_DB, ODOO_USER, ODOO_PASSWORD');
+    }
+    return { url, db, user, pass };
+}
+async function authenticate() {
+    if (_session)
+        return _session;
+    const { url, db, user, pass } = cfg();
+    const res = await fetch(`${url}/web/session/authenticate`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            jsonrpc: '2.0', method: 'call', id: 1,
+            params: { db, login: user, password: pass },
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`Odoo auth HTTP ${res.status}`);
+    const data = await res.json();
+    if (data.error)
+        throw new Error(`Odoo auth error: ${data.error.message}`);
+    if (!data.result?.uid)
+        throw new Error('Odoo auth failed — no uid returned (wrong credentials?)');
+    _session = { uid: data.result.uid, sessionId: data.result.session_id };
+    return _session;
+}
+async function odooCall(model, method, args, kwargs = {}) {
+    const sess = await authenticate();
+    const { url } = cfg();
+    const res = await fetch(`${url}/web/dataset/call_kw`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Cookie': `session_id=${sess.sessionId}`,
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0', method: 'call', id: Date.now(),
+            params: { model, method, args, kwargs },
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`Odoo ${model}.${method} HTTP ${res.status}`);
+    const data = await res.json();
+    if (data.error) {
+        throw new Error(`Odoo ${model}.${method}: ${data.error.data?.message ?? data.error.message}`);
+    }
+    return data.result;
+}
+// ── Tools ─────────────────────────────────────────────────────────────────────
+function buildServer() {
+    const srv = new mcp_js_1.McpServer({ name: 'bk-mcp-odoo', version: '0.1.0' });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const t = srv.tool.bind(srv);
+    t('odoo_employee_create', 'Create a new employee record in Odoo HR.', {
+        name: zod_1.z.string().describe('Full name'),
+        work_email: zod_1.z.string().email().optional().describe('Work email address'),
+        job_title: zod_1.z.string().optional().describe('Job title'),
+        department: zod_1.z.string().optional().describe('Department name (partial match)'),
+    }, async ({ name, work_email, job_title, department }) => {
+        const vals = { name };
+        if (work_email)
+            vals.work_email = work_email;
+        if (job_title)
+            vals.job_title = job_title;
+        if (department) {
+            const ids = await odooCall('hr.department', 'search', [[['name', 'ilike', department]]]);
+            if (ids.length)
+                vals.department_id = ids[0];
+        }
+        const id = await odooCall('hr.employee', 'create', [vals]);
+        return { content: [{ type: 'text', text: `Employee created. Odoo ID: ${id}` }] };
+    });
+    t('odoo_employee_get', 'Retrieve employee records from Odoo by ID or name search.', {
+        employee_id: zod_1.z.number().optional().describe('Exact employee ID'),
+        name: zod_1.z.string().optional().describe('Name filter (partial match)'),
+        limit: zod_1.z.number().optional().describe('Maximum records to return (default 5)'),
+    }, async ({ employee_id, name, limit }) => {
+        let domain;
+        if (employee_id !== undefined) {
+            domain = [['id', '=', employee_id]];
+        }
+        else if (name) {
+            domain = [['name', 'ilike', name]];
+        }
+        else {
+            domain = [['active', '=', true]];
+        }
+        const records = await odooCall('hr.employee', 'search_read', [], {
+            domain,
+            fields: ['id', 'name', 'work_email', 'job_title', 'department_id', 'active'],
+            limit: limit ?? 5,
+        });
+        if (!records.length) {
+            return { content: [{ type: 'text', text: 'No employees found.' }] };
+        }
+        const lines = records.map(r => {
+            const dept = r.department_id;
+            return [
+                `ID: ${r.id}`,
+                `Name: ${r.name}`,
+                `Title: ${r.job_title ?? '—'}`,
+                `Dept: ${dept ? dept[1] : '—'}`,
+                `Email: ${r.work_email ?? '—'}`,
+            ].join(' | ');
+        });
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    t('payroll_prepare', 'Create a draft payroll slip (hr.payslip) for an employee and period.', {
+        employee_id: zod_1.z.number().describe('Odoo employee ID'),
+        date_from: zod_1.z.string().describe('Period start date (YYYY-MM-DD)'),
+        date_to: zod_1.z.string().describe('Period end date (YYYY-MM-DD)'),
+    }, async ({ employee_id, date_from, date_to }) => {
+        const payslipId = await odooCall('hr.payslip', 'create', [{
+                employee_id,
+                date_from,
+                date_to,
+            }]);
+        return {
+            content: [{ type: 'text', text: `Payslip created. ID: ${payslipId}  State: draft` }],
+        };
+    });
+    t('payroll_confirm', 'Compute salary lines and confirm (validate) a payroll slip.', {
+        payslip_id: zod_1.z.number().describe('Payslip ID returned by payroll_prepare'),
+    }, async ({ payslip_id }) => {
+        await odooCall('hr.payslip', 'compute_sheet', [[payslip_id]]);
+        await odooCall('hr.payslip', 'action_payslip_done', [[payslip_id]]);
+        return {
+            content: [{ type: 'text', text: `Payslip ${payslip_id} confirmed. State: done` }],
+        };
+    });
+    return srv;
+}
+// ── Start ─────────────────────────────────────────────────────────────────────
+const { httpMode, port } = (0, server_runner_js_1.parseCliArgs)();
+(0, server_runner_js_1.runMcpServer)(buildServer, { httpMode, port, label: 'bk-mcp-odoo' }).catch(err => {
+    process.stderr.write(`[bk-mcp-odoo] Fatal: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/odoo/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/odoo/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@backendkit-labs/mcp-connectors",
-  "version": "0.1.0",
-  "description": "Enterprise MCP connectors — HubSpot CRM, Jira, Google Calendar",
+  "version": "0.1.2",
+  "description": "Enterprise MCP connectors — HubSpot CRM, Jira, Google Calendar, Odoo ERP",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
     "bk-mcp-hubspot": "./dist/hubspot/server.js",
     "bk-mcp-jira":    "./dist/jira/server.js",
-    "bk-mcp-gcal":    "./dist/gcal/server.js"
+    "bk-mcp-gcal":    "./dist/gcal/server.js",
+    "bk-mcp-odoo":    "./dist/odoo/server.js"
   },
   "files": ["dist/", "README.md"],
   "repository": {