MCP Integration Server

# MCP Integration Server (Salesforce • Atlassian • Supabase) A TypeScript Model Context Protocol (MCP) server that exposes your Salesforce, Atlassian (Jira/Confluence), and internal resources as tools and resources agents can call in a standardized way. ## This README covers: What the server does How to configure credentials How to build and run locally How to smoke-test tools without any desktop client Operational/safety notes # At a glance Language/Runtime: TypeScript on Node 18+ (Node 20+ recommended) MCP Transport: stdio (the MCP server is launched by the client and communicates over standard I/O) Key integrations: Salesforce REST, Jira/Confluence REST, Supabase (logging + example resources) Hardening included: central HTTP client with timeouts, basic log redaction, environment isolation Repo layout ## Repo layout ```text MCPtest-main/ ├─ mcp-server/ │ ├─ index.ts # MCP server (stdio) wiring handlers for tools/resources │ ├─ types.ts # Tool/Resource typing helpers │ ├─ runtime/ │ │ ├─ context.ts # Central env + Supabase client │ │ └─ http.ts # Shared axios instance (timeouts, sane defaults) │ ├─ tools/ │ │ ├─ salesforce.ts # salesforce_* tools (query/get/search + writes) │ │ ├─ atlassian.ts # jira_* / confluence_* tools │ │ ├─ analytics.ts # example tools backed by Supabase │ │ ├─ documents.ts # example doc tools backed by Supabase │ │ └─ utilities.ts # calculate, format_date, generate_uuid, hash_string, http_request │ ├─ resources/ │ │ ├─ salesforce.ts # salesforce://* read-only resources │ │ ├─ atlassian.ts # jira://* / confluence://* resources │ │ ├─ analytics.ts # analytics://* resources from Supabase │ │ └─ documents.ts # document://* resources from Supabase │ └─ tsconfig.json ├─ scripts/ │ ├─ mcp-smoketest.mjs # headless tool caller (launches server over stdio) │ └─ list-tools.mjs # prints all tool names ├─ .env.example ├─ package.json └─ README.md ``` Prerequisites Node.js 18+ (20+ recommended) An editor with TypeScript support (Optional) Accounts/API tokens for Salesforce, Jira, Confluence, Supabase Environment variables Copy .env.example to .env in the project root and fill in what you need. Only the integrations you use must be set. Supabase (used for logging + example resources) Variable Description SUPABASE_URL Your Supabase project URL SUPABASE_ANON_KEY or SUPABASE_SERVICE_ROLE_KEY Key to access your Supabase (start with ANON; use Service Role only with proper RLS) Backward-compatible names VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY are still read by runtime/context.ts, but prefer the SUPABASE_* names for clarity. # Salesforce ``` Variable Description SALESFORCE_INSTANCE_URL e.g., https://your-domain.my.salesforce.com SALESFORCE_ACCESS_TOKEN OAuth/Bearer token with appropriate scopes Jira (Atlassian) Variable Description JIRA_URL e.g., https://your-domain.atlassian.net JIRA_EMAIL Atlassian account email JIRA_API_TOKEN API token generated from Atlassian account Confluence (Atlassian) Variable Description CONFLUENCE_URL e.g., https://your-domain.atlassian.net/wiki CONFLUENCE_EMAIL Atlassian account email CONFLUENCE_API_TOKEN API token generated from Atlassian account Tip: Start with read-only tools (queries, searches) before enabling any write-paths. ``` # Install, build, and run locally From the project root: Install deps npm install Build the MCP server npm run build:mcp This compiles TypeScript to mcp-server/dist/index.js. Smoke-test a tool (no desktop client required) The smoketest script launches the MCP server over stdio and calls a tool by name. Show available tools (optional): node scripts/list-tools.mjs Call a safe tool first (from utilities.ts), e.g.: ## mac/linux node scripts/mcp-smoketest.mjs calculate '{"expression":"2+2*5"}' ## windows powershell (escape quotes) node scripts/mcp-smoketest.mjs calculate "{""expression"":""2+2*5""}" Call an integration tool (only after your .env is set), for example: ## Salesforce (read-only) node scripts/mcp-smoketest.mjs salesforce_query '{"query":"SELECT Id, Name FROM Account LIMIT 1"}' ## Jira (search) node scripts/mcp-smoketest.mjs jira_search_issues '{"jql":"assignee = currentUser() ORDER BY created DESC"}' What you should see: JSON output with a content array containing the tool’s result (in text-serialized JSON). If an auth error appears, recheck your .env. # How it works (short version) mcp-server/index.ts stands up a JSON-RPC MCP Server over stdio with handlers for: ListTools → discovers all tools (from tools/) CallTool → routes tool calls to the correct handler ListResources/ReadResource → exposes read-only document/analytics/salesforce/atlassian resources mcp-server/runtime/context.ts centralizes: Environment variable parsing Supabase client creation mcp-server/runtime/http.ts provides a shared axios instance with: 20s timeout Controlled status handling Tools log to Supabase’s api_logs (if configured). Arguments are passed through a small redaction helper to avoid storing secrets. # Configuration details HTTP client: mcp-server/runtime/http.ts sets a 20s timeout and friendly status handling (validateStatus). If you need retries, add an axios interceptor there once. Logging: Tool handlers call a logApiCall helper that inserts rows into api_logs. Sensitive fields like tokens are redacted before insert. Responses: Tools consistently return { content: [{ type: "text", text: "<JSON-string>" }] }. This keeps client parsing predictable across runtimes. # Safety notes Start read-only. Begin with tools like salesforce_query or jira_search_issues. Enable writes (create/update/delete/transition) later. Guard writes. A simple pattern is to require a confirm: "yes" or a dryRun: true default and only execute state-changing calls when explicitly requested. (Planned: dryRun fields on Salesforce/Atlassian write tools.) Least privilege. Use the minimum API scopes necessary for each integration. RLS on Supabase. If you use ANON keys, set Row Level Security so logs are not world-readable. # Troubleshooting Cannot find module mcp-server/dist/index.js You skipped the build step or ran from the wrong folder. Fix: npm run build:mcp then ensure mcp-server/dist/index.js exists. Hangs or very slow responses External API may be slow. Timeouts are set to 20s; adjust in runtime/http.ts if needed. Auth errors Double-check your .env. Try a non-integrated tool (calculate) to confirm the server/client plumbing. Tool not found Run node scripts/list-tools.mjs to see the exact tool names, then pass one to the smoketest. # Extending Add new integrations by creating a new file in mcp-server/tools/yourservice.ts and registering tools that return structured results. Expose read-only views through mcp-server/resources/yourservice.ts with your own URI scheme (e.g., yourservice://…). If you later use a GUI agent runtime or desktop client, point it at node mcp-server/dist/index.js as an MCP stdio server. # Scripts reference package.json (root) includes: build:mcp – compile the MCP server mcp:server – run the compiled server directly (usually launched by a client) (optional) tools – list tool names (optional) smoke – shorthand to run the smoketestMCPtest