# Tool Sync: Bidirectional Azure DevOps Synchronization
## Overview
**Tool Sync** is a powerful and flexible command-line tool that provides bidirectional synchronization between Azure DevOps work items and local files. Unlike other tools that are often unidirectional or limited to specific work item types, Tool Sync allows you to keep any type of work item (User Stories, Bugs, Tasks, etc.) in sync with local files in your Git repository.
This enables a "Work-Items-as-Code" approach, where your Azure DevOps project can be treated as a single source of truth that is perfectly mirrored in a local directory, allowing you to leverage the power of your favorite text editors and version control systems to manage your work.
## Features
- **Bidirectional Synchronization:** Changes made locally or in Azure DevOps are reflected on the other side.
- **Generic Work Item Support:** Sync any type of work item, not just Test Cases or User Stories.
- **Configurable Mappings:** Define which work item types to sync, where to store them, and in what format.
- **Local File Representation:** Work items are stored as local files (e.g., Markdown with YAML front matter), making them easy to read, edit, and version control.
- **"Last Write Wins" Strategy:** The tool uses a timestamp-based "last write wins" strategy to handle updates.
## Installation
`tool-sync` offers two installation options depending on your needs.
### Standard Installation (Synchronization only)
For the core synchronization features, you can install the package directly using pip:
```bash
pip install tool-sync
```
This will provide you with the `tool_sync sync` command and all necessary functionality to synchronize your work items.
### Installation with Analysis Features
To use the AI-powered analysis server with assistants like Cline, you need to install the package with the `[analysis]` extra. This includes additional libraries for vector indexing and language processing.
```bash
pip install "tool-sync[analysis]"
```
## Configuration
Tool Sync is configured via a `config.yml` file in your project's root directory. This file defines a list of "sync mappings", where each mapping is a rule that connects a remote Azure DevOps query to a local directory.
**NEW in 0.5.0:** You can now sync work items from **multiple projects** in the same configuration file.
Here is a detailed example `config.yml` demonstrating multi-project synchronization:
```yaml
# A list of synchronization rules.
sync_mappings:
# Example 1: Sync User Stories from 'Project Alpha' for Team A
- name: "Alpha Project - Team A Stories"
# --- Connection details for this specific mapping ---
azure_devops:
organization_url: "https://dev.azure.com/your_org"
project_name: "Project Alpha"
personal_access_token: "your_pat_goes_here"
# --- Sync rules for this mapping ---
work_item_type: "User Story"
local_path: "work_items/project_alpha/stories"
area_path: 'Project Alpha\\Team A' # Syncs only items from this Area Path
file_format: "md"
fields_to_sync:
- System.State
- Microsoft.VSTS.Common.Priority
template: |
---
id: {{ id }}
type: {{ type }}
title: '{{ title }}'
state: {{ fields['System.State'] | default('New') }}
priority: {{ fields['Microsoft.VSTS.Common.Priority'] | default(2) }}
---
{{ description }}
# Example 2: Sync all Bugs from a different project, 'Project Bravo'
- name: "Bravo Project - All Bugs"
# --- Connection details for Project Bravo ---
azure_devops:
organization_url: "https://dev.azure.com/your_org" # Can be the same or a different org
project_name: "Project Bravo"
personal_access_token: "your_other_pat_if_needed"
# --- Sync rules for this mapping ---
work_item_type: "Bug"
local_path: "work_items/project_bravo/bugs"
# No area_path is specified, so it will sync all bugs from Project Bravo.
file_format: "md"
template: |
---
id: {{ id }}
title: '{{ title }}'
state: {{ fields['System.State'] | default('New') }}
severity: {{ fields['Microsoft.VSTS.Common.Severity'] | default('3 - Medium') }}
---
**Bug Description:**
{{ description }}
```
### Configuration Options
Each entry in the `sync_mappings` list has the following options:
- `name`: A descriptive name for the mapping (e.g., "Frontend Team Bugs").
- `azure_devops`: **(Required)** Contains the connection details for this specific mapping.
- `organization_url`: The URL of your Azure DevOps organization.
- `project_name`: The name of the Azure DevOps project for this mapping.
- `personal_access_token`: Your Personal Access Token (PAT) for authentication.
- `work_item_type`: **(Required)** The type of work item to sync (e.g., "User Story", "Bug").
- `local_path`: **(Required)** The local directory where the files for these work items will be stored.
- `area_path` (Optional): The Azure DevOps Area Path to filter by. If provided, only work items under this path will be synchronized.
- `fields_to_sync` (Optional): A list of additional Azure DevOps fields to sync.
- `file_format`: **(Required)** The file extension for the local files (e.g., `md`, `json`).
- `template` (Optional): The Jinja2 template to use for generating the content of the local files. If omitted, a default template is used.
## Usage
To run the synchronization, simply execute the following command in your terminal:
```bash
tool_sync sync
```
The tool will read your `config.yml`, connect to Azure DevOps, and perform the synchronization based on your defined mappings.
### Creating New Work Items
You can create a new work item in Azure DevOps by creating a new file in the corresponding local directory. The file should follow the format defined in your template, but without an `id` field in the front matter.
For example, to create a new User Story, you could create a new file `work_items/user_stories/my-new-story.md` with the following content:
```yaml
---
type: User Story
state: New
created_date: '2023-10-27T10:00:00Z'
changed_date: '2023-10-27T10:00:00Z'
title: 'My New User Story'
---
# My New User Story
This is the description of my new user story.
```
The next time you run `tool_sync sync`, the tool will detect this new file, create a corresponding User Story in Azure DevOps, and then update the local file with the newly assigned ID.
## AI-Powered Analysis with Cline
`tool_sync` is more than just a synchronization tool. It includes a powerful **AI analysis engine** that can be used as a local MCP (Model Context Protocol) server for AI assistants like the [Cline VS Code extension](https://marketplace.visualstudio.com/items?itemName=cline.bot).
This allows you to have rich, context-aware conversations about your project's data, ask complex questions, find patterns, and identify root causes.
### How It Works
The analysis engine uses a **Retrieval-Augmented Generation (RAG)** pipeline. When you start the server, it can index all your local work item files into a local vector database. When you ask a question via Cline, the server finds the most relevant documents and provides them as context to the LLM, leading to highly accurate and relevant answers.
### Using the Analysis Engine with Cline
To use the AI-powered analysis features, you will need an MCP client like the [Cline VS Code extension](https://marketplace.visualstudio.com/items?itemName=cline.bot). The following steps will guide you through the setup and usage.
#### Step 1: Configure the Cline MCP Server
This is the most crucial step. You need to tell Cline how to start the `tool_sync` server.
1. **Find the settings file:** In VS Code, click on the **MCP Servers** icon in the activity bar. This will open a new panel.
2. **Open the configuration:** In the MCP Servers panel, go to the **Installed** tab, find your `tool_sync_analyzer` server (it may appear here after the first attempt to use it), or simply click the "Configure MCP Servers" button or link. This will open the `cline_mcp_settings.json` file.
3. **Update the configuration:** Paste the following JSON into the file. You **must** replace the placeholder path with the **absolute path** to the Python executable in your virtual environment.
```json
{
"mcpServers": {
"tool_sync_analyzer": {
"command": "C:\\path\\to\\your\\project\\.venv\\Scripts\\python.exe",
"args": [
"-m",
"tool_sync.main",
"analyze"
],
"disabled": false,
"timeout": 3600
}
}
}
```
**Configuration Notes:**
- **`command`**: This **must** be the full, absolute path to your Python executable. On Windows, use double backslashes (`\\`). To find the path, activate your virtual environment and run `where python` (Windows) or `which python` (Linux/macOS).
- **`timeout`**: Increasing the timeout to `3600` seconds can help prevent the server from stopping during long-running tasks like indexing.
4. **Restart VS Code:** It's good practice to restart VS Code to ensure Cline picks up the new configuration.
#### Step 2: Verify the Connection
After restarting VS Code, open the Cline chat. Type `@` and a list of available tools should appear. If you see **`@tool_sync_analyzer`** in the list, the connection was successful!
#### Step 3: Index Your Knowledge Base
Before you can ask questions, the server needs to build its knowledge base. With the new version, you can index **multiple folders**, including your work items, source code, and automated tests.
In the Cline chat, send a command listing all the paths you want to index. **Paths can be absolute or relative.**
**Example for indexing work items and source code:**
> @tool_sync_analyzer index_documents paths=['work_items/', 'src/', 'tests/']
**Example using absolute paths (useful if running `tool_sync` from a different directory):**
> @tool_sync_analyzer index_documents paths=['D:\\my_project\\work_items', 'D:\\my_project\\src']
You should receive a success message like: `"Successfully indexed all provided paths. The knowledge base is ready."`
This makes the analysis engine much more powerful, as it can now answer questions about your source code and tests in addition to your work items. It also allows the `tool_sync` server to be run from anywhere, as long as you provide absolute paths to the content you want to analyze.
#### Step 4: Ask Questions!
Now you can query your knowledge base. Ask questions related to the content of your work item files.
Example prompts for Cline:
- `@tool_sync_analyzer query_documents question='What is the most common cause of login errors?'`
- `@tool_sync_analyzer query_documents question='Summarize all defects related to the new API'`
The server will respond with the most relevant documents it found, providing rich, project-specific context for your questions.
Raw data
{
"_id": null,
"home_page": "https://github.com/fabioribeiroquispe/tool_sync",
"name": "tool-sync",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "azure devops, sync, synchronization, work items",
"author": "F\u00e1bio Ribeiro dos Santos Quispe",
"author_email": "fabiorisantos1981@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/46/0f/8c169053ba0fa756a480d647079cfadfedc9d3b6a52a9771bf697699d1e8/tool_sync-0.6.5.tar.gz",
"platform": null,
"description": "# Tool Sync: Bidirectional Azure DevOps Synchronization\n\n## Overview\n\n**Tool Sync** is a powerful and flexible command-line tool that provides bidirectional synchronization between Azure DevOps work items and local files. Unlike other tools that are often unidirectional or limited to specific work item types, Tool Sync allows you to keep any type of work item (User Stories, Bugs, Tasks, etc.) in sync with local files in your Git repository.\n\nThis enables a \"Work-Items-as-Code\" approach, where your Azure DevOps project can be treated as a single source of truth that is perfectly mirrored in a local directory, allowing you to leverage the power of your favorite text editors and version control systems to manage your work.\n\n## Features\n\n- **Bidirectional Synchronization:** Changes made locally or in Azure DevOps are reflected on the other side.\n- **Generic Work Item Support:** Sync any type of work item, not just Test Cases or User Stories.\n- **Configurable Mappings:** Define which work item types to sync, where to store them, and in what format.\n- **Local File Representation:** Work items are stored as local files (e.g., Markdown with YAML front matter), making them easy to read, edit, and version control.\n- **\"Last Write Wins\" Strategy:** The tool uses a timestamp-based \"last write wins\" strategy to handle updates.\n\n## Installation\n\n`tool-sync` offers two installation options depending on your needs.\n\n### Standard Installation (Synchronization only)\n\nFor the core synchronization features, you can install the package directly using pip:\n\n```bash\npip install tool-sync\n```\n\nThis will provide you with the `tool_sync sync` command and all necessary functionality to synchronize your work items.\n\n### Installation with Analysis Features\n\nTo use the AI-powered analysis server with assistants like Cline, you need to install the package with the `[analysis]` extra. This includes additional libraries for vector indexing and language processing.\n\n```bash\npip install \"tool-sync[analysis]\"\n```\n\n## Configuration\n\nTool Sync is configured via a `config.yml` file in your project's root directory. This file defines a list of \"sync mappings\", where each mapping is a rule that connects a remote Azure DevOps query to a local directory.\n\n**NEW in 0.5.0:** You can now sync work items from **multiple projects** in the same configuration file.\n\nHere is a detailed example `config.yml` demonstrating multi-project synchronization:\n\n```yaml\n# A list of synchronization rules.\nsync_mappings:\n # Example 1: Sync User Stories from 'Project Alpha' for Team A\n - name: \"Alpha Project - Team A Stories\"\n # --- Connection details for this specific mapping ---\n azure_devops:\n organization_url: \"https://dev.azure.com/your_org\"\n project_name: \"Project Alpha\"\n personal_access_token: \"your_pat_goes_here\"\n # --- Sync rules for this mapping ---\n work_item_type: \"User Story\"\n local_path: \"work_items/project_alpha/stories\"\n area_path: 'Project Alpha\\\\Team A' # Syncs only items from this Area Path\n file_format: \"md\"\n fields_to_sync:\n - System.State\n - Microsoft.VSTS.Common.Priority\n template: |\n ---\n id: {{ id }}\n type: {{ type }}\n title: '{{ title }}'\n state: {{ fields['System.State'] | default('New') }}\n priority: {{ fields['Microsoft.VSTS.Common.Priority'] | default(2) }}\n ---\n {{ description }}\n\n # Example 2: Sync all Bugs from a different project, 'Project Bravo'\n - name: \"Bravo Project - All Bugs\"\n # --- Connection details for Project Bravo ---\n azure_devops:\n organization_url: \"https://dev.azure.com/your_org\" # Can be the same or a different org\n project_name: \"Project Bravo\"\n personal_access_token: \"your_other_pat_if_needed\"\n # --- Sync rules for this mapping ---\n work_item_type: \"Bug\"\n local_path: \"work_items/project_bravo/bugs\"\n # No area_path is specified, so it will sync all bugs from Project Bravo.\n file_format: \"md\"\n template: |\n ---\n id: {{ id }}\n title: '{{ title }}'\n state: {{ fields['System.State'] | default('New') }}\n severity: {{ fields['Microsoft.VSTS.Common.Severity'] | default('3 - Medium') }}\n ---\n **Bug Description:**\n {{ description }}\n```\n\n### Configuration Options\n\nEach entry in the `sync_mappings` list has the following options:\n\n- `name`: A descriptive name for the mapping (e.g., \"Frontend Team Bugs\").\n- `azure_devops`: **(Required)** Contains the connection details for this specific mapping.\n - `organization_url`: The URL of your Azure DevOps organization.\n - `project_name`: The name of the Azure DevOps project for this mapping.\n - `personal_access_token`: Your Personal Access Token (PAT) for authentication.\n- `work_item_type`: **(Required)** The type of work item to sync (e.g., \"User Story\", \"Bug\").\n- `local_path`: **(Required)** The local directory where the files for these work items will be stored.\n- `area_path` (Optional): The Azure DevOps Area Path to filter by. If provided, only work items under this path will be synchronized.\n- `fields_to_sync` (Optional): A list of additional Azure DevOps fields to sync.\n- `file_format`: **(Required)** The file extension for the local files (e.g., `md`, `json`).\n- `template` (Optional): The Jinja2 template to use for generating the content of the local files. If omitted, a default template is used.\n\n## Usage\n\nTo run the synchronization, simply execute the following command in your terminal:\n\n```bash\ntool_sync sync\n```\n\nThe tool will read your `config.yml`, connect to Azure DevOps, and perform the synchronization based on your defined mappings.\n\n### Creating New Work Items\n\nYou can create a new work item in Azure DevOps by creating a new file in the corresponding local directory. The file should follow the format defined in your template, but without an `id` field in the front matter.\n\nFor example, to create a new User Story, you could create a new file `work_items/user_stories/my-new-story.md` with the following content:\n\n```yaml\n---\ntype: User Story\nstate: New\ncreated_date: '2023-10-27T10:00:00Z'\nchanged_date: '2023-10-27T10:00:00Z'\ntitle: 'My New User Story'\n---\n\n# My New User Story\n\nThis is the description of my new user story.\n```\n\nThe next time you run `tool_sync sync`, the tool will detect this new file, create a corresponding User Story in Azure DevOps, and then update the local file with the newly assigned ID.\n\n## AI-Powered Analysis with Cline\n\n`tool_sync` is more than just a synchronization tool. It includes a powerful **AI analysis engine** that can be used as a local MCP (Model Context Protocol) server for AI assistants like the [Cline VS Code extension](https://marketplace.visualstudio.com/items?itemName=cline.bot).\n\nThis allows you to have rich, context-aware conversations about your project's data, ask complex questions, find patterns, and identify root causes.\n\n### How It Works\n\nThe analysis engine uses a **Retrieval-Augmented Generation (RAG)** pipeline. When you start the server, it can index all your local work item files into a local vector database. When you ask a question via Cline, the server finds the most relevant documents and provides them as context to the LLM, leading to highly accurate and relevant answers.\n\n### Using the Analysis Engine with Cline\n\nTo use the AI-powered analysis features, you will need an MCP client like the [Cline VS Code extension](https://marketplace.visualstudio.com/items?itemName=cline.bot). The following steps will guide you through the setup and usage.\n\n#### Step 1: Configure the Cline MCP Server\n\nThis is the most crucial step. You need to tell Cline how to start the `tool_sync` server.\n\n1. **Find the settings file:** In VS Code, click on the **MCP Servers** icon in the activity bar. This will open a new panel.\n2. **Open the configuration:** In the MCP Servers panel, go to the **Installed** tab, find your `tool_sync_analyzer` server (it may appear here after the first attempt to use it), or simply click the \"Configure MCP Servers\" button or link. This will open the `cline_mcp_settings.json` file.\n\n3. **Update the configuration:** Paste the following JSON into the file. You **must** replace the placeholder path with the **absolute path** to the Python executable in your virtual environment.\n\n ```json\n {\n \"mcpServers\": {\n \"tool_sync_analyzer\": {\n \"command\": \"C:\\\\path\\\\to\\\\your\\\\project\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\n \"-m\",\n \"tool_sync.main\",\n \"analyze\"\n ],\n \"disabled\": false,\n \"timeout\": 3600\n }\n }\n }\n ```\n\n **Configuration Notes:**\n - **`command`**: This **must** be the full, absolute path to your Python executable. On Windows, use double backslashes (`\\\\`). To find the path, activate your virtual environment and run `where python` (Windows) or `which python` (Linux/macOS).\n - **`timeout`**: Increasing the timeout to `3600` seconds can help prevent the server from stopping during long-running tasks like indexing.\n\n4. **Restart VS Code:** It's good practice to restart VS Code to ensure Cline picks up the new configuration.\n\n#### Step 2: Verify the Connection\n\nAfter restarting VS Code, open the Cline chat. Type `@` and a list of available tools should appear. If you see **`@tool_sync_analyzer`** in the list, the connection was successful!\n\n#### Step 3: Index Your Knowledge Base\n\nBefore you can ask questions, the server needs to build its knowledge base. With the new version, you can index **multiple folders**, including your work items, source code, and automated tests.\n\nIn the Cline chat, send a command listing all the paths you want to index. **Paths can be absolute or relative.**\n\n**Example for indexing work items and source code:**\n> @tool_sync_analyzer index_documents paths=['work_items/', 'src/', 'tests/']\n\n**Example using absolute paths (useful if running `tool_sync` from a different directory):**\n> @tool_sync_analyzer index_documents paths=['D:\\\\my_project\\\\work_items', 'D:\\\\my_project\\\\src']\n\nYou should receive a success message like: `\"Successfully indexed all provided paths. The knowledge base is ready.\"`\n\nThis makes the analysis engine much more powerful, as it can now answer questions about your source code and tests in addition to your work items. It also allows the `tool_sync` server to be run from anywhere, as long as you provide absolute paths to the content you want to analyze.\n\n#### Step 4: Ask Questions!\n\nNow you can query your knowledge base. Ask questions related to the content of your work item files.\n\nExample prompts for Cline:\n- `@tool_sync_analyzer query_documents question='What is the most common cause of login errors?'`\n- `@tool_sync_analyzer query_documents question='Summarize all defects related to the new API'`\n\nThe server will respond with the most relevant documents it found, providing rich, project-specific context for your questions.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A bidirectional synchronization tool for Azure DevOps work items.",
"version": "0.6.5",
"project_urls": {
"Homepage": "https://github.com/fabioribeiroquispe/tool_sync"
},
"split_keywords": [
"azure devops",
" sync",
" synchronization",
" work items"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ea8c5ab4ae3414f4de7178ab8fe1ebf730b44ce5c326e5d599850ca9ec9c50b5",
"md5": "1680001f9a8171466d68de3ab8c5bb2a",
"sha256": "ca6a435567ff16738c66ac85c85c5bf34cd3140628cdb616d9615766c03e60ab"
},
"downloads": -1,
"filename": "tool_sync-0.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1680001f9a8171466d68de3ab8c5bb2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19708,
"upload_time": "2025-08-31T04:58:07",
"upload_time_iso_8601": "2025-08-31T04:58:07.423615Z",
"url": "https://files.pythonhosted.org/packages/ea/8c/5ab4ae3414f4de7178ab8fe1ebf730b44ce5c326e5d599850ca9ec9c50b5/tool_sync-0.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "460f8c169053ba0fa756a480d647079cfadfedc9d3b6a52a9771bf697699d1e8",
"md5": "f55e6f35721a98b6b2c02bca05eb114d",
"sha256": "9339b3c05b71535da6ac04a1edd40d641009a285cd36986f66042f36861259e9"
},
"downloads": -1,
"filename": "tool_sync-0.6.5.tar.gz",
"has_sig": false,
"md5_digest": "f55e6f35721a98b6b2c02bca05eb114d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23637,
"upload_time": "2025-08-31T04:58:08",
"upload_time_iso_8601": "2025-08-31T04:58:08.932752Z",
"url": "https://files.pythonhosted.org/packages/46/0f/8c169053ba0fa756a480d647079cfadfedc9d3b6a52a9771bf697699d1e8/tool_sync-0.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 04:58:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fabioribeiroquispe",
"github_project": "tool_sync",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tool-sync"
}
JSON
