connected-workspace-mcp 1.0.0

package/docs/installation.md

@@ -0,0 +1,84 @@
+# Installation And MCP Setup
+
+## Requirements
+
+- Node.js 20 or newer
+- An MCP-compatible host such as VS Code
+- Google Cloud OAuth credentials
+- Optional LinkedIn developer application credentials
+
+## Install From npm
+
+Install globally when you want stable command names:
+
+```powershell
+npm install --global connected-workspace-mcp
+```
+
+Available commands:
+
+```text
+connected-workspace-mcp
+connected-workspace-google-auth
+connected-workspace-linkedin-auth
+```
+
+You can also run the server without a global installation:
+
+```powershell
+npx -y connected-workspace-mcp --env-file "C:\Users\you\.connected-workspace-mcp\.env"
+```
+
+## Configure The Environment
+
+Create a private configuration directory, copy `.env.example` from the package
+or repository, and populate the provider client settings. Pass its path with
+`--env-file` when the current working directory does not contain `.env`.
+
+On Windows, explicit persistent paths can look like:
+
+```dotenv
+PA_MCP_TOKEN_PATH=C:/Users/you/.connected-workspace-mcp/tokens.json
+PA_MCP_LOG_PATH=C:/Users/you/.connected-workspace-mcp/server.log
+```
+
+See [configuration.md](configuration.md) for every setting.
+
+## VS Code MCP Configuration
+
+For an npm-installed server, add a server entry equivalent to:
+
+```json
+{
+  "servers": {
+    "connected-workspace": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "connected-workspace-mcp",
+        "--env-file",
+        "C:\\Users\\you\\.connected-workspace-mcp\\.env"
+      ]
+    }
+  }
+}
+```
+
+Alternatively, set provider values in the MCP host's `env` configuration. Never
+place secrets directly in `args`, where process inspection may expose them.
+Restart the MCP server after changing configuration or authorization.
+
+## Local Development
+
+```powershell
+npm install
+Copy-Item .env.example .env
+npm run auth:google
+npm run auth:linkedin
+npm run build
+npm start
+```
+
+The repository includes `.vscode/mcp.json` for running the compiled local
+server.

package/docs/linkedin-auth.md

@@ -0,0 +1,61 @@
+# LinkedIn OAuth Setup
+
+## Create The LinkedIn Application
+
+1. Open https://www.linkedin.com/developers/apps and create or select an app.
+2. Associate and verify the appropriate LinkedIn Page.
+3. Enable **Sign In with LinkedIn using OpenID Connect**.
+4. Enable **Share on LinkedIn**.
+5. Add this exact authorized redirect URL:
+
+```text
+http://localhost:3001/callback
+```
+
+Configure:
+
+```dotenv
+LINKEDIN_CLIENT_ID=your-client-id
+LINKEDIN_CLIENT_SECRET=your-client-secret
+LINKEDIN_REDIRECT_URI=http://localhost:3001/callback
+LINKEDIN_API_VERSION=202609
+```
+
+## Required Scopes
+
+```text
+openid
+profile
+email
+w_member_social
+```
+
+## Authorize
+
+From a source checkout:
+
+```powershell
+npm run auth:linkedin
+```
+
+After a global npm installation:
+
+```powershell
+connected-workspace-linkedin-auth
+```
+
+The callback validates OAuth state, exchanges the authorization code, reads the
+OpenID member identifier, and persists the token with its expiry metadata.
+
+## API Limitations
+
+Standard LinkedIn member APIs can read basic OpenID identity information and
+manage posts when the app has approved products and scopes. They do not permit
+arbitrary edits to headline, experience, education, or skills. Messaging and
+some analytics require partner-only access.
+
+LinkedIn access tokens expire. If LinkedIn does not grant your application a
+refresh token, rerun authorization after expiry.
+
+See [Authentication troubleshooting](troubleshooting.md) for product approval,
+redirect URI, and `401 Unauthorized` checks.

package/docs/publishing.md

@@ -0,0 +1,52 @@
+# Publishing To npm
+
+The package name is `connected-workspace-mcp`. Confirm availability directly
+against npmjs immediately before the first publish.
+
+## Before The First Publish
+
+1. Confirm the GitHub repository URL in `package.json` is public and correct.
+2. Confirm `.env` contains no values that should be copied into documentation.
+3. Rotate any credentials that have been shared outside your password manager.
+4. Add an `NPM_AUTH_TOKEN` repository secret with permission to publish the
+   package.
+
+## Validate
+
+```powershell
+npm run format:check
+npm test
+npm run check
+npm run build
+npm pack --dry-run
+```
+
+The tarball should include only compiled `dist` files, documentation,
+`.env.example`, and top-level package metadata. It must not include `.env`,
+tests, source files, tokens, logs, or coverage output.
+
+## Publish
+
+The recommended release path is to create a GitHub Release with a tag matching
+`v<version>`, for example `v1.0.0`. The release workflow validates the project,
+sets the package version from the tag, and publishes with npm provenance.
+
+For a manual release:
+
+```powershell
+npm login --registry=https://registry.npmjs.org/
+npm publish
+```
+
+The package uses public access and the official npm registry through
+`publishConfig`. The `prepack` script automatically checks formatting, runs all
+tests, and rebuilds before a tarball or publish is created.
+
+For later releases, update the version first:
+
+```powershell
+npm version patch
+npm publish
+```
+
+Use `minor` or `major` instead when the change warrants it.

package/docs/tools.md

@@ -0,0 +1,40 @@
+# Tool Reference
+
+## Gmail
+
+| Tool                   | Purpose                                             |
+| ---------------------- | --------------------------------------------------- |
+| `gmail_search`         | Search with Gmail query syntax and return summaries |
+| `gmail_get_message`    | Read headers and decoded message text               |
+| `gmail_send_message`   | Send a plain-text email                             |
+| `gmail_reply`          | Reply within an existing thread                     |
+| `gmail_modify_message` | Add or remove labels such as `UNREAD` or `STARRED`  |
+
+## Google Calendar
+
+| Tool                    | Purpose                                           |
+| ----------------------- | ------------------------------------------------- |
+| `calendar_list_events`  | List ordered events in a time range               |
+| `calendar_create_event` | Schedule an event and optionally notify attendees |
+| `calendar_update_event` | Patch selected fields on an event                 |
+| `calendar_delete_event` | Delete an event                                   |
+| `calendar_free_busy`    | Read busy periods for one or more calendars       |
+
+## LinkedIn
+
+| Tool                      | Purpose                                       |
+| ------------------------- | --------------------------------------------- |
+| `linkedin_get_profile`    | Read the authenticated OpenID profile         |
+| `linkedin_list_posts`     | List posts authored by the member             |
+| `linkedin_get_post`       | Read a post by URN                            |
+| `linkedin_get_engagement` | Read available social action summaries        |
+| `linkedin_publish_text`   | Publish a text post                           |
+| `linkedin_publish_image`  | Upload a local image and publish it with text |
+| `linkedin_delete_post`    | Permanently delete an owned post              |
+
+## Write Safety
+
+Sending email, modifying labels, creating/updating/deleting events, and
+publishing/deleting posts change live provider data. Configure your MCP host to
+require confirmation for write tools. Automated Jest tests mock every provider
+and never perform these actions on real accounts.

package/docs/troubleshooting.md

@@ -0,0 +1,61 @@
+# Authentication Troubleshooting
+
+Never include client secrets, access tokens, refresh tokens, complete email
+bodies, or complete logs in issues or support requests.
+
+## Google `invalid_grant`
+
+In Google Cloud Console, verify that Gmail API and Google Calendar API are
+enabled and that the OAuth client configured in `.env` is a Desktop app. The
+client ID and secret must belong to the same client, and the redirect URI must
+be exactly:
+
+```text
+http://localhost:3000
+```
+
+If the consent screen is in testing mode, add the account under **Test users**.
+Testing-mode refresh tokens may expire after seven days. Confirm that all four
+required scopes in the [Google setup guide](google-auth.md) are approved.
+
+Common causes include a revoked or expired refresh token, credentials from a
+different OAuth client, a changed account password, too many issued refresh
+tokens, a redirect mismatch, or an incorrect system clock. Remove the old app
+grant at https://myaccount.google.com/connections and authorize again when
+needed.
+
+## LinkedIn `401 Unauthorized`
+
+In LinkedIn Developer Console, verify that the app is active, associated with a
+verified LinkedIn Page, and has active access to both **Sign In with LinkedIn
+using OpenID Connect** and **Share on LinkedIn**. Requested products are not
+usable until LinkedIn approves them.
+
+Confirm the client ID, client secret, required scopes, and this exact redirect:
+
+```text
+http://localhost:3001/callback
+```
+
+A 401 commonly means the access token expired, was revoked, belongs to another
+app, or lacks an approved product or scope. Standard apps may not receive
+refresh tokens, so reauthorization after expiry can be expected.
+
+## Reauthorize And Restart
+
+From a source checkout:
+
+```powershell
+npm run auth:google
+npm run auth:linkedin
+npm run build
+```
+
+For a global npm installation, use
+`connected-workspace-google-auth` or
+`connected-workspace-linkedin-auth`. Restart the MCP server afterward so it
+reloads the token store.
+
+Run `npm run test:auth` to validate local token persistence and client
+construction. Passing mocked tests does not prove that a live provider accepts
+a token.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "connected-workspace-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server for Gmail, Google Calendar, and LinkedIn communication workflows",
+  "author": "Deepak Kamboj",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepakkamboj/connected-workspace-mcp.git"
+  },
+  "homepage": "https://github.com/deepakkamboj/connected-workspace-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/deepakkamboj/connected-workspace-mcp/issues"
+  },
+  "main": "dist/src/index.js",
+  "bin": {
+    "connected-workspace-mcp": "dist/src/index.js",
+    "connected-workspace-google-auth": "dist/src/auth/google/authorize.js",
+    "connected-workspace-linkedin-auth": "dist/src/auth/linkedin/authorize.js"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    ".env.example",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gmail",
+    "google-calendar",
+    "linkedin",
+    "social-networking",
+    "productivity"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "npm run format:check && npm test && npm run build",
+    "test": "jest --runInBand",
+    "test:auth": "jest --runInBand --runTestsByPath tests/auth.test.ts",
+    "test:gmail": "jest --runInBand --runTestsByPath tests/gmail-tools.test.ts",
+    "test:calendar": "jest --runInBand --runTestsByPath tests/calendar-tools.test.ts",
+    "test:linkedin": "jest --runInBand --runTestsByPath tests/linkedin-tools.test.ts tests/linkedin-client.test.ts",
+    "test:coverage": "jest --runInBand --coverage",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/src/index.js",
+    "auth": "npm run auth:google",
+    "auth:google": "tsx src/auth/google/authorize.ts",
+    "auth:linkedin": "tsx src/auth/linkedin/authorize.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "dotenv": "^17.0.0",
+    "googleapis": "^160.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "jest": "^30.5.1",
+    "prettier": "^3.9.6",
+    "ts-jest": "^29.4.12",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}