We welcome contributions to SEC EDGAR MCP. This guide will help you get started with contributing code, documentation, bug reports, and feature requests.

​
Ways to Contribute

Code Contributions

Fix bugs, add features, or improve performance

Documentation

Improve docs, add examples, or fix typos

Bug Reports

Report issues or unexpected behavior

Feature Requests

Suggest new tools or improvements

​
Getting Started

​
Development Environment Setup

1

Fork and Clone

# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/sec-edgar-mcp.git
cd sec-edgar-mcp
2

Set Up Development Environment

# Install UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Set up environment variables
export SEC_EDGAR_USER_AGENT="Your Name (your.email@domain.com)"
export PYTHONPATH=$(pwd):$PYTHONPATH
3

Install Pre-commit Hooks

# Install pre-commit hooks for code quality
uv run pre-commit install

# Run hooks on all files (optional)
uv run pre-commit run --all-files
4

Verify Installation

# Test the installation
uv run python -m sec_edgar_mcp.server --help

# Run tests
uv run pytest

​
Development Workflow

  1. Create a branch: 
    git checkout -b feature/your-feature-name
  2. Make changes following our coding standards
  3. Test your changes: 
    # Run tests
uv run pytest

# Run type checking
uv run mypy sec_edgar_mcp/

# Run linting
uv run ruff check sec_edgar_mcp/
  4. Commit and push: 
    git add .
git commit -m "feat: add new feature description"
git push origin feature/your-feature-name
  5. Open a Pull Request on GitHub

​
Code Guidelines

​
Python Code Style

We use strict code quality tools:

​
Code Structure

Follow these patterns: 
# Good: Clear function with docstring and types
async def get_filing_content(url: str, timeout: int = 30) -> Dict[str, Any]:
    """
    Retrieve filing content from SEC EDGAR.
    
    Args:
        url: The SEC EDGAR filing URL
        timeout: Request timeout in seconds
        
    Returns:
        Dictionary containing filing content and metadata
        
    Raises:
        ValueError: If URL is invalid
        requests.RequestException: If request fails
    """
    if not url.startswith("https://www.sec.gov/"):
        raise ValueError("Invalid SEC EDGAR URL")
    
    # Implementation here
    
# Bad: No types, no docstring
def get_filing(url):
    return requests.get(url).json()

​
Adding New Tools

When adding new MCP tools:
1

Plan the Tool

  • Define the tool’s purpose
  • Specify input parameters
  • Design the output format
  • Consider error cases
2

Implement the Tool

@app.tool()
async def new_tool_name(
    param1: str,
    param2: Optional[int] = None
) -> Dict[str, Any]:
    """
    Tool description for documentation.
    
    Args:
        param1: Description of first parameter
        param2: Optional second parameter
        
    Returns:
        Dictionary with tool results
    """
    # Validate inputs
    if not param1:
        raise ValueError("param1 is required")
    
    # Implementation
    result = await some_async_operation(param1, param2)
    
    return {
        "tool": "new_tool_name",
        "result": result,
        "metadata": {
            "timestamp": datetime.now().isoformat(),
            "version": "1.0"
        }
    }
3

Add Tests

import pytest
from unittest.mock import AsyncMock, patch

@pytest.mark.asyncio
async def test_new_tool_name():
    """Test the new tool functionality."""
    # Mock external dependencies
    with patch('sec_edgar_mcp.server.some_async_operation') as mock_op:
        mock_op.return_value = {"data": "test"}
        
        # Test the tool
        result = await new_tool_name("test_param")
        
        # Assertions
        assert result["tool"] == "new_tool_name"
        assert result["result"]["data"] == "test"
        mock_op.assert_called_once_with("test_param", None)
4

Update Documentation

  • Add tool to README.md
  • Create usage examples
  • Update tool count in documentation

​
Pull Request Process

​
PR Requirements

​
Commit Message Convention

We follow conventional commits: 
# Types: feat, fix, docs, style, refactor, test, chore
git commit -m "feat: add support for Form 13F parsing"
git commit -m "fix: handle missing CIK in submissions"
git commit -m "docs: update installation instructions"
git commit -m "test: add tests for XBRL parsing"

​
PR Template

Use this template for pull requests: 
## Description
Brief description of what this PR does.

## Changes
- [ ] Add new feature X
- [ ] Fix bug Y
- [ ] Update documentation

## Testing
- [ ] All existing tests pass
- [ ] New tests added for changes
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Breaking changes documented

​
Issue Reporting

​
Bug Reports

Use the bug report template: 
**Bug Description**
Clear description of what the bug is.

**Reproduction Steps**
1. Call tool with parameters...
2. See error...

**Expected Behavior**
What should happen instead.

**Environment**
- SEC EDGAR MCP version:
- Python version:
- Operating system:
- MCP client:

**Additional Context**
Any other relevant information.

​
Feature Requests

Use the feature request template: 
**Feature Description**
Clear description of the proposed feature.

**Use Case**
Why would this feature be valuable?

**Proposed Solution**
How do you envision this working?

**Alternatives**
Any alternative approaches considered?

​
Community Guidelines

​
Code of Conduct

We are committed to providing a welcoming and inclusive environment:
  • Be respectful in all interactions
  • Be collaborative and help others
  • Be professional in communications
  • Be inclusive and welcoming to newcomers

​
Getting Help

Discord Community

Join our Discord for real-time help and discussions

GitHub Discussions

Use GitHub Discussions for longer-form questions

Documentation

Check the docs before asking questions

Stack Overflow

Tag questions with sec-edgar-mcp

​
Recognition

Contributors are recognized in several ways:
  • README contributors section
  • Release notes mentions
  • Community highlights
  • Maintainer opportunities for regular contributors

​
Release Process

For maintainers:
1

Prepare Release

  • Update version in pyproject.toml
  • Update CHANGELOG.md
  • Run full test suite
2

Create Release

# Tag the release
git tag v1.2.3
git push origin v1.2.3

# Build and publish
uv build
uv publish
3

Post-Release

  • Update documentation
  • Announce on social media
  • Close resolved issues
Created and maintained by Stefano Amorelli. Built together with the community.Thank you for contributing to SEC EDGAR MCP! Your contributions help make financial data more accessible to everyone.