README - atlassian-community-mcp-server by nealriley

Atlassian Community MCP Server

A search service for the Atlassian Community built using the Model Context Protocol (MCP). This project enables AI assistants and other applications to search, retrieve, and analyze content from the Atlassian Community forums.

Project Overview

The Atlassian Community MCP server provides endpoints for searching community posts, filtering by tags, retrieving trending content, and accessing user contributions. It's designed to be used by AI agents, integrations, and tools that need to access Atlassian Community content programmatically.

Local Development

To set up and run this project locally for development:

Clone the repository:

git clone https://github.com/yourusername/atlassian-community-mcp-server.git
cd atlassian-community-mcp-server

Install dependencies:
```
npm install
```
Start the development server:
```
npm run dev
```
Your MCP server will be available at: http://localhost:8787/mcp (The SSE endpoint will be at: http://localhost:8787/sse)
For health check, visit: http://localhost:8787/health

Adding Tests

This project uses Jest for testing. To add and run tests:

Create test files with the .test.ts extension in the same directory as the file you're testing

Write your tests using the Jest testing framework. Example:

// services.test.ts
import { searchByQuery } from './services';

describe('searchByQuery', () => {
  test('should return search results', async () => {
    const results = await searchByQuery('test', 5, 0, 'desc');
    expect(results).toHaveProperty('success');
    expect(results).toHaveProperty('items');
  });
});

Run all tests:
```
npm test
```
Run a specific test file:
```
npm test -- services.test.ts
```
For faster testing during development, you can also use the test-functions script:
```
npx tsx src/test-functions.ts
```

Feature Requests and Bug Reports

We use GitHub issues to track feature requests and bug reports. To open a new issue:

Go to the GitHub Issues page
Click on "New Issue"
Choose the appropriate template (Feature Request or Bug Report)
Fill out the required information:
- For feature requests: describe the desired functionality, why it's needed, and any implementation ideas
- For bug reports: provide steps to reproduce, expected behavior, actual behavior, and environment details
Submit the issue

Submitting Pull Requests

We welcome contributions! To submit a pull request:

Fork the repository

Create a new branch for your feature or fix:

git checkout -b feature/your-feature-name

git checkout -b fix/issue-you-are-fixing

Make your changes and commit them with descriptive commit messages:
```
git commit -m "Add new feature: detailed description"
```

Push your branch to your fork:

git push origin feature/your-feature-name

Open a pull request:
- Go to the original repository
- Click "Pull Requests" and then "New Pull Request"
- Choose "compare across forks"
- Select your fork and branch
- Fill out the PR template with a description of your changes
- Reference any related issues using the "Fixes #issue-number" syntax
Wait for code review
Address any feedback and update your PR as needed

Development Guidelines

Follow the TypeScript coding style used throughout the project
Add comments for complex logic
Write tests for new features
Update documentation when adding or changing features

Project Structure

├── src/                    # Source files and Jest tests
│   ├── index.ts           # Main entry point, MCP server setup and endpoint definitions
│   ├── services.ts        # Core service functions that interact with the Atlassian Community API
│   ├── services.test.ts   # Tests for service functions
│   ├── utils.ts           # Utility functions for API requests, formatting, logging
│   └── test-functions.ts  # Script to test service functions directly
└── jest.config.js         # Jest configuration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Connect to AI Assistants

Cloudflare AI Playground

Go to https://playground.ai.cloudflare.com/
Enter your deployed MCP server URL (atlassian-community-mcp-server.<your-account>.workers.dev/sse)
You can now use your MCP tools directly from the playground!

Claude Desktop

To connect to your remote MCP server from Claude Desktop, follow Anthropic's Quickstart and within Claude Desktop go to Settings > Developer > Edit Config.

Update with this configuration:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"  // or your deployed URL
      ]
    }
  }
}

Development

Project Structure

src/index.ts - Main MCP server definition and tool configuration
src/services.ts - Service functions for interacting with the Atlassian Community API
src/utils.ts - Utility functions for logging, formatting, and API requests
src/services.test.ts - Tests for service functions

Developing New Tools

To add a new tool to the MCP server:

Add a new service function in src/services.ts that fetches data from the Atlassian Community API
Add a corresponding test in src/services.test.ts
Add a new tool definition in src/index.ts using this.server.tool()
Update the README.md to document the new tool

Commands

npm run dev - Start the development server
npm run deploy - Deploy to Cloudflare Workers
npm run format - Format code using Biome
npm run lint:fix - Lint and fix code using Biome