Glean MCP Server implementation

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+    env:
+      VOLTA_FEATURE_PNPM: 1
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js and pnpm with Volta
+        uses: volta-cli/action@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run linter
+        run: pnpm lint
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to @gleanwork/server-glean
+
+Thank you for your interest in contributing to the Glean MCP Server! This document provides guidelines and instructions for development.
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/gleanwork/server-glean.git
+cd server-glean
+```
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+1. Run tests:
+
+```bash
+npm test
+```
+
+1. Build the project:
+
+```bash
+npm run build
+```
+
+## Running the Server Locally
+
+The server communicates via stdio, making it ideal for integration with AI models and other tools:
+
+```bash
+node build/index.js
+```
+
+Input and output follow the JSON-RPC 2.0 protocol, with each message on a new line.
+
+## Making Changes
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/my-feature`
+3. Commit your changes: `git commit -am 'Add new feature'`
+4. Push to the branch: `git push origin feature/my-feature`
+5. Submit a pull request
+
+## Code Style
+
+- Use TypeScript for all new code
+- Follow the existing code style (enforced by ESLint and Prettier)
+- Include JSDoc comments for public APIs
+- Write tests for new functionality
+
+## Testing
+
+- Add unit tests for new features
+- Ensure all tests pass before submitting a pull request
+- Use the provided test utilities and fixtures
+
+## Documentation
+
+- Update documentation for any changed functionality
+- Include examples for new features
+- Keep the README.md and API documentation up to date
+
+## Need Help?
+
+- Documentation: [docs.glean.com](https://docs.glean.com)
+- Issues: [GitHub Issues](https://github.com/gleanwork/server-glean/issues)
+- Email: [support@glean.com](mailto:support@glean.com)

README.md

@@ -1,153 +1,81 @@
-# Typescript Template (Typescript Starter Project) for Node Modules and CLIs
-
-- 🚀 Start coding immediately, without worrying about configuration
-- 📰 Publish your package to NPM with only a few tweaks
-- 🧹 Use a tidy file structure that is already set up for dev
-- 🧪 Test suite ready to fill out
-- 💻 Deliver a Command Line Interface version of your project
-- ✨ Auto-format your code with Prettier
-- 🔬 Find issues with ESLint
-- ⚡ Includes Visual Studio Code extension recommendations and default settings, for maximum productivity out of the box
-
-Getting a Typescript project running
-is a pain, since there is a lot of environment and configuration setup
-before you can get started. If you want to be able to publish
-your Typescript project to [npm](https://www.npmjs.com/) there is even more
-configuration to ensure that you are only (and definitely) pushing the files
-that are strictly needed. Finally, setting up testing can be confusing,
-especially since test code also needs to be compiled but should not be
-included with your published npm package.
-
-This starter kit aims to alleviate all the annoyance of setting up a modern
-Typescript project for Node packages.
-
-## ⚠ Caveats ⚠
-
-- This template is for Node, not Browser, projects.
-- To support Node versions <14 you may need to change the `tsconfig.json` target settings.
-
-## Setup Guide
-
-### Dependencies
-
-- [**Node.js v13.2+**](https://nodejs.org/) (v14+ highly recommended)
-
-### Preparing a new project
-
-#### The easy way: GitHub Templates
-
-[This project](https://github.com/bscotch/typescript-template) is set up as a GitHub template.
-
-1. Click the "Use this Template" button on the project homepage to create your own
-   remote repo with everything here. Follow the prompts.
-2. On your local machine, use GitHub Desktop to clone the repo, or
-   navigate to the parent folder where you want to keep your
-   local repo copy and run `git clone your-remote-url`.
-
-#### The hard way: All CLI, all the time
-
-1. Create a new remote repo on your host (e.g. GitHub, BitBucket, GitLab, etc.)
-1. Go to the local parent folder into which you want to put your new Typescript project
-   (via your file explorer or a terminal)
-1. Clone this repo locally: `git clone --branch develop git@github.com:bscotch/typescript-template.git`
-1. Rename the folder containing this repo (`typescript-template`) to your project's name
-1. Go to your new local repo (via a Git GUI or a terminal (with `cd your-new-name`))
-1. (Optional) If you don't want the git history from this template to be included in your project's history:
-1. Delete the `.git` folder
-1. Run `git init` (or use a Git GUI to initialize the repo)
-1. Change the remote to your own remote repository: `git remote set-url origin your-remote-url` (or, if you initialized a new repo, add your remote with `git remote add origin your-remote-url`)
-
-#### Customize the template
-
-1. Run `npm install` to install all dependencies
-2. (Optional) Run `npm outdated` to see if any dependencies have major updates.
-3. (Optional) Run `npm update` to get those dependencies up to date with minor updates.
-4. Update the `package.json` with your project's details
-   - Set the `name` field. If you are going to publish to npm, this will be the name of your package. Must be a URL-friendly name. Best practice is to use kebab-case (all lower-case, alphanumeric and dashes).
-   - Set the `description` field.
-   - Set the `repository` field to your remote git repo's URL.
-   - Set the `homepage` field (your remote git repo's URL works fine for this).
-   - Add any `keywords` strings. If you publish to npm, these will be used by searches.
-   - Remove the `private` field **if you want to publish to npm**.
-   - If you do not want to publish to npm, remove `&& npm publish` from the `scripts.postversion` script.
-5. Check the `.gitignore` and add any filetypes or folders you want to keep out of your repo.
-6. Remove any stuff from the template that you don't care about. (You can do this at any time.)
-7. Open up the `./tsconfig.json` file to see if you want to change anything. Pay particular attention to the `paths` section!
-8. Commit all your changes: `git add -A; git commit`
-9. Push your commit: `git push`
-
-### Begin coding!
-
-- Your entrypoint is `./src/index.ts`, so start there!
-- Your compiled code will appear in a git-ignored `build` folder, with entrypoint `build/index.js`.
-- To compile, run `npm run build`
-- To auto-recompile while you code, run `npm run build-live`
-- Sample folders and files for types and your code library are placed in `src/lib` and `src/types`.
-- If you intend to use the `fs-extra` module for anything in your non-test code,
-  move it from the `devDependencies` to the `dependencies` section of your `package.json`.
-
-### Creating a CLI (Command Line Interface)
-
-This template project comes with the [commander module](https://www.npmjs.com/package/commander),
-which is great for rapidly building command line interfaces
-(uninstall it with `npm uninstall commander` if you don't need to make a CLI).
-
-To create a CLI that will become available when someone installs your npm package:
-
-- Rename `src/cli/cli.ts` to `src/cli/your-main-cli-name.ts`. This is the entrypoint
-  for your CLI.
-- Name any subcommand files to `src/cli/your-main-cli-name-subcommand.ts`.
-  Update the CLI entrypoint to use the same subcommand names.
-  Subcommand scripts _must_ start with the same name as your main CLI script,
-  and _must_ end with an exact command name listed by its parent script
-  (one of the `cli.command()` values).
-- Modify the CLI templates to do whatever it's all supposed to do.
-- To make `your-cli-command` available to users who install your
-  npm package, add the `bin` field to your `package.json`, like so:
-  ```jsonc
-  {
-    //... other root package.json options
-    "bin": {
-      "your-cli-command": "build/cli/your-main-cli-name.js"
-    }
-  }
-  ```
-
-Test your CLI locally by running `node build/cli/your-main-cli-name.js -h`.
-
-If you publish your project as an npm module, users who install it will be able
-to run `npx your-cli-command` in their terminals, or simply `your-cli-command`
-if they've done a global install of your module (with `npm install --global your-module-name`).
-
-### Testing
-
-- Add tests to `./src/test` as you go.
-- Place any reference data for tests into `./samples`
-- Run tests from the terminal with `npm test` (make sure your code is compiled first).
-- Run tests from VSCode (click the debugger on the sidebar) to use breakpoints and allow inspection:
-  - Use the "Tests" option to run against your compiled code.
-  - Console logs will appear in the Debug Console, where you can also step through your code if you set breakpoints.
-  - Edit `./.vscode/launch.json` to add or change the tests.
-
-### Versioning and publishing to npm
-
-When you are ready to increment the version of your project, which by default
-is coupled to publishing to `npm` and merging into your `main` branch
-(edit this behavior in the `scripts` section of the `package.json`),
-use the `npm version` commands. For example:
-
-- `npm version patch` to bump the patch version, indicated a bugfix
-- `npm version minor` to bump the minor version, indicating a new feature (backwards-compatible)
-- `npm version major` to bump the major version, indicating substantial and/or breaking changes
-
-The `preversion`, `version`, and `postversion` scripts in the `package.json` file dictate what happens
-when you use an `npm version` command. By default, the sequence of things that happen are:
-
-1. Source is compiled into plain JavaScript.
-2. Tests are run against the compiled JavaScript. If any fail, the process aborts.
-3. Increment the version number in the `package.json` file.
-4. Update `CHANGELOG.md` to reflect the new version.
-5. `git add` all file changes.
-6. Commit changes and create a version tag.
-7. Push changes to remote
-8. Publish package to `npm`.
+# @gleanwork/server-glean
+
+A Model Context Protocol (MCP) server implementation for Glean's search and chat capabilities. This server provides a standardized interface for AI models to interact with Glean's content search and conversational AI features through stdio communication.
+
+## Features
+
+- 🔍 **Search Integration**: Access Glean's powerful content search capabilities
+- 💬 **Chat Interface**: Interact with Glean's AI assistant
+- 🔄 **MCP Compliant**: Implements the Model Context Protocol specification
+
+## Prerequisites
+
+- Node.js v18 or higher
+- Glean API credentials
+
+## Installation
+
+```bash
+npm install @gleanwork/server-glean
+```
+
+## Configuration
+
+1. Set up your Glean API credentials:
+
+```bash
+export GLEAN_SUBDOMAIN=your_subdomain
+export GLEAN_API_TOKEN=your_api_token
+```
+
+1. (Optional) For global tokens that support impersonation:
+
+```bash
+export GLEAN_ACT_AS=user@example.com
+```
+
+## Tools
+
+### search
+
+Search Glean's content index using the Glean Search API. This tool allows you to query Glean's content index with various filtering and configuration options.
+
+For complete parameter details, see [Search API Documentation](https://developers.glean.com/client/operation/search/)
+
+### chat
+
+Interact with Glean's AI assistant using the Glean Chat API. This tool allows you to have conversational interactions with Glean's AI, including support for message history, citations, and various configuration options.
+
+For complete parameter details, see [Chat API Documentation](https://developers.glean.com/client/operation/chat/)
+
+## Running the Server
+
+The server communicates via stdio, making it ideal for integration with AI models and other tools:
+
+```bash
+node build/index.js
+```
+
+## Running in inspect mode
+
+The server can also be run in inspect mode, which provides additional debugging information:
+
+```bash
+pnpm inspect
+```
+
+This will run MCP's inspector, which allows you to execute and debug calls to the server.
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details
+
+## Support
+
+- Documentation: [docs.glean.com](https://docs.glean.com)
+- Issues: [GitHub Issues](https://github.com/gleanwork/server-glean/issues)
+- Email: [support@glean.com](mailto:support@glean.com)